Token format
Authorization codes, access tokens and refresh tokens: how long each lasts, what a token contains, and how the API verifies it.
access_token and refresh_token are standard JWTs signed with HS256. Paste one into any JWT decoder to read it. Authorization codes are not JWTs. They are short, opaque, single-use strings.
The three credentials
| Credential | Lifetime | Format |
|---|---|---|
| Authorization code | 10 minutes, single use | 32-character hex string |
| Access token | 1 day | JWT with typ: "access" |
| Refresh token | 365 days | JWT with typ: "refresh" |
JWT shape
Header:
{
"alg": "HS256",
"typ": "JWT"
}Payload of an access token:
{
"typ": "access",
"app_id": "<APP_ID>",
"user_id": 123,
"install_id": 7,
"scopes": ["contacts.read", "contacts.write"],
"iss": "<ISSUER>",
"aud": "<YOUR_CLIENT_ID>",
"sub": "123",
"iat": 1716200000,
"exp": 1716286400
}| Claim | Meaning |
|---|---|
typ | access or refresh. The API refuses a refresh token sent as a Bearer token. |
app_id | Your app. |
user_id, sub | The installing user. Tokens are bound to this user. |
install_id | This installation of your app. |
scopes | The scopes granted at install time. The API checks the current grant on every request, so this list can lag behind a scope change. |
iss | An opaque, fixed value the API checks. You do not need to. |
aud | The client_id of the integration the token was minted for. |
iat, exp | Issued at and expiry, as Unix seconds. |
Verification
The API verifies a token on every request: the HS256 signature, exp, iss and typ. It also checks that the installation is still active, so a revoked installation stops working immediately even though its tokens are not yet expired.
Treat iss as a value the API owns. If you build token-validation middleware on top of these tokens, validate aud against your own client_id and exp against the clock. The signing key stays on the API, so your code decodes the payload but cannot check the signature. The API checks it on every request.
Handling tokens
- Store the access token and the refresh token together, keyed by the installing user.
- When a request answers
401, refresh and replace both. See Authentication. - The previous refresh token stays valid until its own expiry. Keep only the newest pair, and treat an old pair as a secret to destroy, not a spare.