RFC-0042: Authentication Token Rotation

Status: Accepted · Owner: Platform · Last modified 2026-08-11

3.1 Scope. This document specifies the rotation procedure for access tokens and refresh tokens issued by the identity service (hereafter IS) to first-party and third-party clients. It supersedes the token handling guidance in RFC-0017 §4 and applies to all clients authenticating against the v2 token endpoint.

3.2 Token lifetimes. 3.2.1 Access tokens SHALL have a lifetime of 900 seconds from issuance. Clients MUST NOT cache access tokens beyond this interval. 3.2.2 Refresh tokens SHALL have a lifetime of 30 days and SHALL be single-use; each successful exchange at POST /v2/token with grant_type=refresh_token SHALL invalidate the presented refresh token and issue a new refresh token alongside the new access token (rotation). 3.2.3 Reuse of an invalidated refresh token SHALL be treated as a compromise signal and SHALL cause IS to revoke the entire token family for that session (see 3.3).

3.3 Revocation. Upon detection of refresh token reuse, IS SHALL revoke all tokens descending from the originating authorization and SHALL emit a session.revoked event to the audit stream. Clients receiving HTTP 401 with error=invalid_grant MUST discard local token state and re-initiate the authorization flow.

3.4 Migration. Clients currently authenticating against /v1/token (non-rotating refresh tokens, 90-day lifetime) MUST migrate to /v2/token before 2026-11-01, at which point /v1/token SHALL return HTTP 410. Mobile clients SHOULD ship rotation support no later than the 2026-10 release train to allow for app store propagation. Partner integrations are subject to the same deadline; the partner SDK ≥ 4.2.0 implements rotation transparently.

3.5 Clock skew. IS SHALL accept access tokens presented up to 60 seconds after nominal expiry to accommodate client clock skew. Clients SHOULD NOT rely on this allowance.

RFC-0042, explained · Platform team

Tokens now rotate. Here's what changes for you.

Access tokens expire after 15 minutes and refresh tokens are single-use. Every refresh hands you a new pair. Old-style /v1/token stops working on November 1.

If you only read one line: move to /v2/token, store the new refresh token after every exchange, and treat a 401 invalid_grant as "start over."

How a session works now

What you need to do

Web team

Switch the token endpoint to /v2/token. After each refresh, overwrite the stored refresh token; the old one is dead the moment the new one arrives.

Mobile team

Same change, and it has to be in the October release train so app stores propagate before the deadline. Assume some users update late: handle 410 gracefully.

Partners

Upgrade to SDK 4.2.0 or later. Rotation is handled for you. Anything older stops authenticating on November 1.

The clock on this

The rules, without the RFC voice

Situation	What happens	What to do
Access token is older than 15 minutes	Requests fail	Refresh. Don't cache past expiry.
You refresh	You get a new access token and a new refresh token	Store the new refresh token immediately
You reuse a refresh token you already spent	Treated as a compromise; every token in the session is revoked	You'll get 401 `invalid_grant`. Clear state and sign in again.
Your clock is a little off	Tokens are accepted up to 60 seconds past expiry	Don't design around this

Deadline: November 1, 2026. After that, /v1/token returns 410 and nothing on it works. Questions go to #platform or on this page.