Skip to main content
User access tokens are short-lived JWTs. When one expires, exchange the refresh token you received alongside it for a new access token.
Two different flows. This page covers API-key applications operating on your own account. If you are an OAuth platform application acting on a customer’s account, refresh customer tokens through the OAuth token refresh endpoint instead — see Refresh an OAuth access token.

​
How the two tokens relate

Two things catch people out. The refresh call authorizes with your API key, not with the expired access token. And it returns only a new access token — the refresh token you already hold stays valid and is not replaced.

​
Where the refresh token comes from

generateUserAccessToken returns a refresh token alongside the access token. Request it explicitly — if you only select token and scopes, you never receive one:
Store the refreshToken server-side with the access token. See API credentials for the full minting call.

​
Refresh the token

refreshUserAccessToken authorizes with your API key, not with the expired access token.
1

Call refreshUserAccessToken

Replace <YOUR_SANDBOX_API_KEY> and <YOUR_REFRESH_TOKEN> with your values:
2

Store the new access token

The response carries a fresh access token and the scopes it grants:
Use the new token in the Authorization: Bearer <YOUR_USER_ACCESS_TOKEN> header, exactly as before.
The refresh response does not include a new refresh token. refreshUserAccessToken returns only token and scopes. Keep the refresh token you received from generateUserAccessToken.

​
When to refresh

Refresh proactively — at the start of a job or session — rather than waiting for a request to fail with a 401 and refreshing reactively. That keeps requests from failing under load. If you no longer hold a valid refresh token, mint a new access token from scratch with generateUserAccessToken.

​
Next steps

API credentials

Mint your first access token and see the full set of arguments.

Authentication

The complete authentication model, including OAuth grants for customer-scoped tokens.