Token lifetimes & refresh
A login yields short-lived ID and access tokens and, when you ask for it, a long-lived refresh token to mint fresh ones without sending the user back through the login page. The defaults are sensible; you can tune them per client within bounds.
Defaults
| Token | Default lifetime | What it is |
|---|---|---|
| ID token | 1 hour | The signed identity token — your app's proof of who logged in. |
| Access token | 1 hour | Bearer token for userinfo; for an API resource, a per-resource JWT with its own TTL. |
| Refresh token | 14 days | Opaque token to obtain new access/ID tokens without re-login. |
| Authorization code | 10 minutes | Single-use, exchanged at the token endpoint. |
The ID and access tokens are deliberately short — an hour bounds the blast radius of a leaked token, and a refresh token (or a fresh login) replaces them silently.
Getting a refresh token
A refresh token is gated, not automatic. You get one only when all of these hold:
- The client is allowed the
refresh_tokengrant. - The authorization request includes the
offline_accessscope. - The request also carries
prompt=consent.
Drop any one and no refresh token is issued. This is the same gate described in Scopes & claims; the curl guide shows the exact request parameters.
Tuning per client
An owner can override a client's ID-token and refresh-token lifetimes with update_client_token_ttls, within bounds that mirror the IDP's own clamp exactly:
| Override | Min | Max |
|---|---|---|
id_token_ttl | 60 s | 14,400 s (4 h) |
refresh_token_ttl | 60 s | 4,838,400 s (56 days) |
The ceilings are 4× the defaults — a misconfigured value can never mint a year-long token. The bounds are enforced at the management API, so a value outside the range is rejected (400), not silently clamped: what you set is what the IDP honors.
You can shorten a TTL freely down to the 60-second floor, but you can only lengthen it up to 4× the default. If you ask for a longer id_token than 4 hours or a longer refresh than 56 days, the request is refused — raise a shorter value or reconsider the design rather than expecting a clamp.
Using and revoking a refresh token
Exchange a refresh token at the token endpoint (grant_type=refresh_token) to get a new access token and ID token. In phase 1 the refresh token itself is reusable — it stays valid until its own lifetime elapses or you revoke it; auth.is does not rotate it to a new value on each use.
Revocation is immediate and server-side. Post a token to the revocation endpoint (RFC 7009) — for example on logout of a single device — and it stops working at once:
POST https://{slug}.auth.is/oidc/token/revocation token=<refresh_or_access_token>&token_type_hint=refresh_token
A password reset revokes the account's refresh tokens wholesale as part of sweeping its sessions and grants — see Sessions & SSO. The curl guide §7–8 walks refresh and revocation with real commands.
API access tokens
An access token minted for an API resource is a JWT signed with the issuer's keys, and it uses that resource's configured access-token TTL (default 1 hour), independent of the client's id/refresh overrides. A plain userinfo access token (no resource indicator) is opaque and uses the 1-hour default.