# 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](https://dts-identity.com/docs/quickstarts/protect-an-api.md). |
| **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 in `scope`, and the caller in `sub`. The API validates it offline against the platform's published keys. With [RBAC](https://dts-identity.com/docs/integrations/apis.md#role-based-access-control) 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 / 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](https://dts-identity.com/docs/integrations/apis.md) |
| 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](https://dts-identity.com/docs/integrations/applications.md#token-lifetimes-and-logout) |
| 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](https://dts-identity.com/docs/settings/login.md) |

## 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](https://dts-identity.com/docs/integrations/applications.md#token-lifetimes-and-logout). How the platform session, application sessions, and an upstream identity provider's session relate is covered in [User lifecycle: Sessions](https://dts-identity.com/docs/directories/user-lifecycle.md#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.

## Related

- [Protect an API](https://dts-identity.com/docs/quickstarts/protect-an-api.md): validating access tokens in your own API.
- [APIs](https://dts-identity.com/docs/integrations/apis.md): scopes, audiences, and per-API token settings.
- [Applications](https://dts-identity.com/docs/integrations/applications.md): per-application token and logout settings.
- [Login settings](https://dts-identity.com/docs/settings/login.md): the SSO session timeouts.
