Guides

Refresh an Access Token

Workspace access tokens expire. Use the refresh token from the initial OAuth exchange to obtain a new access token without sending the user through consent again.

Store refresh tokens securely

Refresh tokens are long-lived credentials. Encrypt them at rest and never expose them in client-side code or logs.

Token lifetimes

After OAuth consent, the token exchange response includes accessTokenExpiresAt and refreshTokenExpiresAt. Typical defaults are a 3-hour access token and a 90-day refresh token. Hosted environments may configure different values — always read the expiry timestamps from the response and refresh before the access token expires.

Token exchange response (example)

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "accessTokenExpiresAt": "2026-06-06T15:00:00.000Z",
  "refreshTokenExpiresAt": "2026-09-04T12:00:00.000Z",
  "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "workspaceName": "Acme Books"
}

When to refresh

Refresh proactively before the access token expires, or reactively when API calls return 401 with an expired token message. The token exchange response includes accessTokenExpiresAt so you can schedule refresh ahead of expiry.

Refresh request

After the user completes workspace OAuth consent, you receive an access token and refresh token. When the access token expires, call:

Workspace refresh

POST /partners/refresh-user-access-token
Content-Type: application/json
x-client-id: your-client-id
x-signature: ...
x-timestamp: ...

{
  "grantType": "refresh_token",
  "refreshToken": "your-refresh-token"
}

The response includes a new access token and optionally a rotated refresh token. Update your stored tokens and retry the failed request.

Signing the refresh request

Token exchange and refresh routes require HMAC signing but do not require a Bearer access token. Sign with your client secret using the JSON body for the body hash segment.

See Authentication & signing and use the signature generator to verify your implementation.