Authentication

OAuth2 client-credentials authentication — minting tokens, scopes, IP allowlisting, secret rotation, and environment isolation.

The API uses the OAuth2 client-credentials grant — the standard flow for backend, server-to-server integrations. There is no browser or session login: your service exchanges a client id and secret for a short-lived bearer token, then sends that token on each request.

Credentials

Your CanopyWMS administrator issues you an API credential, which carries:

a client id and client secret (the secret is shown once at creation);
a set of scopes (least-privilege; see below);
an optional IP allowlist (CIDR ranges that may use the credential);
a rate limit (requests per minute);
a tenant, and optionally a single pinned client (brand).

Credentials are per environment — sandbox credentials only work against api.staging.canopywms.com, production credentials only against api.canopywms.com.

Getting a token

POST /oauth/token with a client_credentials grant. Send the client id and secret either as HTTP Basic auth or as form fields.

Mint an access token

curl -X POST https://api.staging.canopywms.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Response

{
  "access_token": "eyJhbGciOiJIUzI1Ni..._jwt_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "orders:read orders:write shipping:read"
}

Tokens are valid for 1 hour (expires_in: 3600). A well-behaved integration mints roughly one token per hour and caches it; the token endpoint is rate-limited to protect against secret brute-forcing.

Calling the API

Send the token as a bearer token on every request:

Authenticated request

curl https://api.staging.canopywms.com/api/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Token claims (tenant, client, scopes, rate limit, allowed IPs) are baked in at issuance, so each request is a fast signature check. Revoking a credential stops new tokens immediately; any token already minted stays valid until it expires (≤ 1 hour).

Scopes

Tokens are least-privilege: a credential only carries the scopes it was granted, and an endpoint rejects a token that lacks the required scope.

Scope	Grants
`orders:read`	Read orders and order history
`orders:write`	Create and update orders, holds, releases, and cancellations
`receiving:read`	Read inbound shipments / purchase orders
`receiving:write`	Create and update inbound shipments / purchase orders
`shipping:read`	Read shipments, tracking, and label costs
`shipping:write`	Create labels and manage shipments
`inventory:read`	Read SKUs and stock levels
`returns:read`	Read returns / RMAs

A token may only call endpoints that explicitly accept API credentials and that match one of its scopes; everything else returns 403. This is fail-closed by design — management surfaces (issuing credentials, configuring channels, etc.) are never reachable with an API token.

Least privilege

Use the narrowest credential for the job: grant only the scopes you actually call, prefer a credential pinned to a single client over a tenant-wide one (a tenant-wide credential can act across every client in the tenant; a pinned one is confined to that client), and add an IP allowlist wherever your integration has stable egress addresses.

IP allowlisting

A credential can be restricted to a set of source IPs / CIDR ranges. The allowlist is enforced twice:

at token issuance — a request from a non-allowlisted IP is refused (only after the secret verifies, so the allowlist never leaks whether a credential exists); and
on every request — the allowed IPs travel inside the token.

An empty allowlist means unrestricted.

Secret rotation & revocation

Rotate a secret (or revoke a credential) from the CanopyWMS admin settings. Revocation is immediate for new tokens.
Because tokens are self-contained and live up to an hour, plan rotations with that overlap in mind.

Environment isolation

Sandbox and production are fully separate — separate base URLs, separate credentials, separate data. The sandbox mirrors production for the purchase-order lifecycle, order ingestion, label creation, and webhooks, so you can validate an integration end-to-end before switching the base URL and credential to production.

With a token in hand, see Conventions for idempotency, errors, rate limits, and pagination — then Endpoints.