Each application has two TTLs you set: access-token lifetime and refresh-token lifetime. The defaults are conservative and good for most apps. Tune deliberately when you have a reason.
Where to set them
Section titled “Where to set them”Application detail → Settings tab → Token Lifetimes.
- Access token TTL — default 1 hour (3600 seconds).
- Refresh token TTL — default 14 days for browser apps, 90 days for native apps.
- Refresh token rotation — on by default.
The shape of the trade-off
Section titled “The shape of the trade-off”Two competing forces:
- Short tokens = small blast radius if leaked. A stolen 1-hour access token is useful for at most an hour.
- Long tokens = fewer round trips and a smoother user experience. Users don't get logged out as often if the refresh window is long.
The middle path most apps land on:
- Access token: 1 hour. Long enough that your app doesn't refresh on every API call. Short enough that a leak is bounded.
- Refresh token: 14 days (browser) or 90 days (native). Long enough that users don't sign in every day. Short enough that a stale device session ages out.
- Rotation: on. Every refresh issues a new refresh token; the old one is invalidated. Catches stolen refresh tokens through reuse detection.
When to shorten
Section titled “When to shorten”- Highly sensitive APIs — payments, healthcare data, identity admin. Access TTL down to 5-15 minutes. The app refreshes more often; users are more strongly protected if a token leaks.
- Shared-device environments — public kiosks, internal terminals. Both TTLs down (15-min access, 8-hour refresh) so a forgotten sign-in doesn't persist past the user's session.
- Just after a known compromise — temporarily shorten across the affected applications while you rotate credentials.
When to lengthen
Section titled “When to lengthen”- CLI / background-job applications — extend the refresh TTL so the CLI doesn't prompt a user every few weeks. 90 days is the sensible upper bound.
- Mobile apps used infrequently — a user who opens your app once every two months still wants to be signed in. 90-day refresh tokens are reasonable.
Rotation: on by default; almost never turn off
Section titled “Rotation: on by default; almost never turn off”Refresh token rotation means: every successful refresh issues a fresh refresh token and invalidates the previous one. The platform detects when the same refresh token is used twice — strong signal that one of the two uses is from a leaked copy. The platform invalidates the entire token family; both the attacker and the legitimate user are forced to sign in again.
Turning off rotation removes this defence. The only scenario where it's justified is a specific legacy client that can't survive having its refresh token change — and even then, prefer fixing the client.
What "TTL" actually means at the wire
Section titled “What "TTL" actually means at the wire”The access token's exp claim is iat + access_TTL. The receiving API validates exp > now (with a small leeway for clock skew). Past exp, every API call returns 401; the SDK swaps in a fresh access token via the refresh endpoint and the call retries.
The refresh token's lifetime is server-side — there's no JWT exp to check. The platform tracks "this refresh token was issued at T, expires at T + refresh_TTL". After expiry, the refresh call returns invalid_grant and the user is forced through full sign-in.
Common questions
Section titled “Common questions”"Why is my user being signed out unexpectedly?" Almost always the refresh TTL or refresh-token rotation reuse-detection firing. Both are visible in audit. See token-expired developer troubleshooting.
"Can I have different TTLs per user?" No, the TTLs are per-application. The right way to give specific users shorter sessions is a different application (where you can configure shorter TTLs) — sometimes used for staff-internal vs customer-facing surfaces.
"Can the access token live longer than 24 hours?" Yes, the platform doesn't enforce a hard cap. We don't recommend it — long access tokens are the dangerous kind in a leak scenario. If you find yourself wanting > 24h, ask whether you actually want a longer refresh TTL (which auto-renews access) instead.
"Does extending the TTL apply to already-issued tokens?" No. Existing tokens carry their original exp. The new TTL applies to tokens issued after the change.