> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  Refresh tokens are issued during onboarding. If you don't have one yet, see [Seller Management](/guides/marketplace-channels/seller-management) for the sign-up flow.
</Info>

## Token Exchange

Call `POST /v1/auth` with your refresh token to obtain an access token. See the [Auth API Reference](/api-reference/scx/auth) for the full request and response schema.

```json theme={null}
{
  "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.

<Warning>
  Do not call `POST /v1/auth` for every API request. The Auth API is [rate limited](/guides/marketplace-channels/rate-limits), 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.
</Warning>

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?

<CardGroup cols={2}>
  <Card title="Rate Limits" icon="gauge" href="/guides/marketplace-channels/rate-limits">
    Understand the per-endpoint quotas and 429 handling across all SCX APIs.
  </Card>

  <Card title="Auth API Reference" icon="code" href="/api-reference/scx/auth">
    Endpoint-level reference for `POST /v1/auth`.
  </Card>
</CardGroup>