Skip to Content

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

TokenAddressed toWhat it is forValidated by
ID tokenThe 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 tokenAn 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 tokenThe platform itselfLets 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 in scope, and the caller in sub. The API validates it offline against the platform's published keys. With RBAC enabled it also carries permissions / roles claims.
  • 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 / artifactLifetimeWhere configured
Authorization code1 minute, single useFixed
Access token for an APIDefault 1 day (2 hours through implicit flows)Per API, on its settings tab; see APIs
Access token without a target API (UserInfo)1 hourFixed
Machine-to-machine token without a target API10 minutesFixed
ID tokenDefault 1 hourPer application; see Applications
Refresh token14 days, extended by rotation up to 1 year in totalFixed; see below
Device code10 minutesFixed
Single sign-on sessionIdle and absolute timeoutsInstance-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_access are 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_access survive 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 localStorage or sessionStorage is 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 Authorization header, never in URLs (they end up in proxy and server logs), and never write them to logs yourself.

On this page