Authentication

External integrations authenticate with the OAuth 2.0 client-credentials grant. There is no user in the loop: the credential belongs to your merchant company, and every request it makes is attributed to that company.

Getting a credential

A client_id and client_secret are issued from the DropHub console by a signed-in operator. A credential cannot mint its successor, so this is deliberately not an API call.

The secret is shown once, at creation. DropHub stores only a verifier. If it is lost it cannot be recovered — only rotated from the console.

Requesting a token

HTTP Basic is the preferred way to present the credentials:

curl -X POST "$BASE_URL/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials

Form-body parameters are the supported alternative:

curl -X POST "$BASE_URL/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"

The response is a short-lived signed JWT:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Send it on every /v2/external request:

curl "$BASE_URL/v2/external/webhook" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Scopes

Scope	Grants
`shipments:read`	Read your shipments and their tracking
`shipments:write`	Create and cancel shipments
`webhooks:manage`	Configure your webhook and rotate its secret

A token carries exactly the scopes its credential was granted. A request outside them is rejected with 403, not 401 — the caller is known, and not permitted.

The token request takes no scope parameter. Scopes are a property of the credential, fixed when it was issued. Sending one changes nothing; to change what a credential may do, change the credential.

Token lifecycle

Read expires_in from the token response rather than assuming a duration — it is the only value that stays correct if the lifetime changes.

Cache the token in memory and reuse it until shortly before expiry. Requesting a fresh token per API call is the most common cause of hitting the rate limit on /oauth/token.

Refresh proactively — a little before expiry, not after the first 401. When a request does fail with 401, the response carries a WWW-Authenticate: Bearer challenge; obtain a new token and retry once. Repeated 401s after a fresh token mean the credential was rotated or revoked.

401 means the token is missing, malformed, or expired. 403 means the token is valid but the credential lacks the scope, or the resource belongs to another merchant. Retrying a 403 with the same credential will never succeed.

Token endpoint errors

/oauth/token uses OAuth error semantics, not problem details — it is the one endpoint that does.

Status	`error`	Meaning
`400`	`invalid_request`, `unsupported_grant_type`	The form body is wrong
`401`	`invalid_client`	The credential is unknown, wrong, or revoked
`429`	`rate_limited`	Too many token requests; honour `Retry-After`

Getting Started

Shipments

Events

Request semantics

API reference

Authentication

Getting a credential

Requesting a token

Scopes

Token lifecycle

Token endpoint errors

​Getting a credential

​Requesting a token

​Scopes

​Token lifecycle

​Token endpoint errors

Getting a credential

Requesting a token

Scopes

Token lifecycle

Token endpoint errors