Tokens
What ID, access, and refresh tokens are each for, who validates which, how long they live, and how rotation and safe storage work.
A single sign-in can produce three different tokens, and most integration problems come from mixing up what each one is for. This page is the lookup table: purpose, audience, lifetime, and handling rules per token type.
The three tokens
| Token | Addressed to | What it is for | Validated by |
|---|---|---|---|
| ID token | The application (its client ID is the audience) | Proves who signed in and carries profile claims (sub, name, email, ...). | The application, usually through its OIDC library. |
| Access token | An API (its identifier is the audience) | Authorizes calls to that API, carrying the granted scopes. | The API, on every request; see Protect an API. |
| Refresh token | The platform itself | Lets the application renew its access token later without sending the user back to the login page. | The platform, at the token endpoint. |
The most common mistake is sending the ID token to an API. An ID token authenticates the user to the application and its audience is the application's client ID, so a correctly implemented API rejects it. Send the access token to APIs, and treat it as opaque inside the client: its contents are a contract between the platform and the API, not the application.
Access token formats
- For a registered API (the client passed the API's identifier as the resource indicator): a signed JWT with the API's identifier as
aud, the granted scopes inscope, and the caller insub. The API validates it offline against the platform's published keys. With RBAC enabled it also carriespermissions/rolesclaims. - Without a target API: an opaque token, usable only at the platform's UserInfo endpoint. Opaque tokens (and refresh tokens) can be checked at the standard token-introspection endpoint and cancelled at the revocation endpoint; both are listed in the discovery document. A client may introspect its own tokens; tokens of other clients only an application created in the Admin Console with a client secret or key (a resource server), not one registered dynamically.
Lifetimes
| Token / artifact | Lifetime | Where configured |
|---|---|---|
| Authorization code | 1 minute, single use | Fixed |
| Access token for an API | Default 1 day (2 hours through implicit flows) | Per API, on its settings tab; see APIs |
| Access token without a target API (UserInfo) | 1 hour | Fixed |
| Machine-to-machine token without a target API | 10 minutes | Fixed |
| ID token | Default 1 hour | Per application; see Applications |
| Refresh token | 14 days, extended by rotation up to 1 year in total | Fixed; see below |
| Device code | 10 minutes | Fixed |
| Single sign-on session | Idle and absolute timeouts | Instance-wide under Settings → Login, overridable per directory; see Login settings |
Refresh tokens
When one is issued. The application must have the refresh token grant type enabled. First-party applications (no consent screen) then receive one automatically; applications with Require user consent enabled receive one only when the user granted the offline_access scope.
Rotation. Refresh tokens rotate rather than living forever:
- A public client (single-page or native app, no client secret) receives a replacement refresh token on every use. For browser-based clients the replacement keeps the remaining lifetime, so rotation does not extend it.
- A confidential client keeps its refresh token until roughly 70% of its lifetime has passed; the next use then issues a fresh 14-day token.
- However it rotates, a refresh-token chain ends one year after the original sign-in at the latest; after that the user must sign in again.
A rotated-out (used) refresh token is invalid; if your client persists tokens, always store the newest one from each response.
Revoking. An application can proactively cancel a refresh token at the revocation endpoint (listed in the discovery document), which is good hygiene during your own sign-out. Users can end their sessions from their account portal ("sign out everywhere"), and session-bound tokens end with them; see the next section.
Tokens and sign-out
Sign-out ends the platform's SSO session, but tokens follow their own rules:
- Tokens issued without
offline_accessare bound to the session. Opaque tokens stop working the moment the session ends. - A JWT access token cannot be recalled: APIs validate it offline, so it stays technically usable until its expiry even after sign-out. If that window matters for an API, shorten its access-token lifetime rather than relying on logout.
- Refresh tokens obtained with
offline_accesssurvive sign-out by design (that is what offline access means). They end when they expire, hit the one-year cap, or are revoked. - Applications can be told about the sign-out through back-channel logout; see Token lifetimes and logout. How the platform session, application sessions, and an upstream identity provider's session relate is covered in User lifecycle: Sessions.
Storing tokens
- Against scripts running in the page (cross-site scripting): a token in
localStorageorsessionStorageis readable by any injected script. Browser apps keep tokens in memory only and rely on refresh-token rotation to bridge the short access-token lifetime. - Against other software on the device: a token in a plain file or preference store is one file read away. Native apps use the operating system's protected store (Keychain, Keystore, credential locker).
- Against the browser as a whole: a server-side application never needs the browser to hold a token. Keep tokens on the server, tied to your own session cookie.
- Against leaks in transit and in logs: send tokens only over TLS in the
Authorizationheader, never in URLs (they end up in proxy and server logs), and never write them to logs yourself.
Related
- Protect an API: validating access tokens in your own API.
- APIs: scopes, audiences, and per-API token settings.
- Applications: per-application token and logout settings.
- Login settings: the SSO session timeouts.