Authorization

How to authenticate against the SCX APIs: refresh tokens, access tokens, and Bearer headers.

All SCX APIs (Channel, Seller, Public, Auth) use the same token-based authorization flow. You exchange a long-lived refresh token for a short-lived access token, then pass that access token as a Bearer header on every subsequent request.

Refresh tokens are issued during onboarding. If you don’t have one yet, see Seller Management for the sign-up flow.

Token Exchange

Call POST /v1/auth with your refresh token to obtain an access token. See the Auth API Reference for the full request and response schema.

{
  "scope": "SELLER",
  "authToken": "eyJhbG.....",
  "tokenExpireAt": "2036-04-01T12:00:00+00:00",
  "expiresIn": 360
}

Field	Description
authToken	the access token to use as a Bearer credential.
tokenExpireAt	absolute expiry in ISO 8601.
expiresIn	lifetime in seconds.
scope	the authorization scope tied to your refresh token (for example, CHANNEL or SELLER).

Using the Access Token

Send the access token as a Bearer token in the Authorization header on every SCX API request:

Authorization: Bearer eyJ0eXAi....

Expiry and Refresh

Access tokens are short-lived. Refresh them proactively before tokenExpireAt rather than waiting for a 401 Unauthorized response.

Do not call POST /v1/auth for every API request. The Auth API is rate limited, and excessive authentication requests may result in 429 Too Many Requests responses. Cache and reuse the access token until it is close to expiring, then request a new one.

The following pattern caches the access token and refreshes it only when necessary:

1. On first use, call POST /v1/auth and store the authToken together with its tokenExpireAt value.
2. Before each API request, check whether tokenExpireAt is more than 60 seconds in the future. If it is, reuse the cached token.
3. Otherwise, call POST /v1/auth again using the same refresh token to obtain a new access token.

What’s Next?

Rate Limits

Understand the per-endpoint quotas and 429 handling across all SCX APIs.

Auth API Reference

Endpoint-level reference for POST /v1/auth.