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.

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 (401 Unauthorized), 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