Using a Refresh Token

The refresh token flow is a more secure way to authorize API requests. Instead of using a single long-lived credential directly, you exchange a refresh token for a short-lived access token. When that access token expires, you exchange again.

Note that the refresh token cannot be used by itself to authorize API requests; it always has to be exchanged for a refresh token first.

To use this flow, select the refresh token option when creating a token in Admin → Developer. You'll receive three values at creation time:

• Client ID – identifies your integration

• Client secret – authenticates the exchange request

• Refresh token – used to obtain access tokens

Exchanging a Refresh Token for an Access Token

Send a POST request to the Altium Identity token endpoint.

Token Endpoint

Request Body (application/x-www-form-urlencoded)

grant_type=refresh_token
refresh_token={refresh-token}
client_id={client-id}
client_secret={client-secret}

Response

{
  "access_token": "...",
  "expires_in": 14400,
  "token_type": "Bearer",
  "refresh_token": "...",
  "scope": "..."
}

Use the access_token from the response to authorize API requests. expires_in is in seconds and indicates how long the access token is valid.

curl Example:

curl -X POST https://auth.altium.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token={refresh-token}" \
  --data-urlencode "client_id={client-id}" \
  --data-urlencode "client_secret={client-secret}"

Integrating into Your Application

A typical pattern for long-running integrations:

1. Store the refresh token, client ID, and client secret securely (e.g., environment variables or a secrets manager).

2. On startup, call the token endpoint to obtain a fresh access token.

3. Use the access token for API requests. Cache it until it expires.

4. On expiry (HTTP status 401 Unauthorized, or 200 OK with error code AuthExpiredToken in the GraphQL response), exchange the refresh token again to get a new access token.

Refresh tokens expire after the lifetime configured at creation (up to 1 year). Once a refresh token expires, you'll need to create a new one in Admin → Developer.

See Also

• Using an Access Token