Refresh Token Rotation: Mermaid Sequence Diagram

About Source

Refresh token rotation is a security pattern that extends the lifespan of a user's authenticated session without requiring them to log in again, while significantly reducing the risk of refresh token theft.

Access tokens are kept intentionally short-lived — typically 5 to 60 minutes — to limit the damage window if one is intercepted. When an access token expires, the client uses a refresh token (a long-lived, opaque credential stored securely) to request a new access token without re-prompting the user for credentials.

In simple refresh (without rotation), the same refresh token can be reused indefinitely until it expires. This creates a long-lived secret that, if stolen, gives an attacker persistent access until the token is explicitly revoked. Refresh token rotation eliminates this risk: every time the client exchanges a refresh token for new tokens, the authorization server issues a brand-new refresh token and immediately invalidates the old one.

The critical security property of rotation is automatic theft detection: if an attacker steals a refresh token and uses it after the legitimate client has already rotated it, the authorization server detects a reuse of an already-invalidated token. The server responds by revoking the entire token family — forcing re-authentication. This means the legitimate user loses their session, but the attack is contained.

Clients must handle the rotation carefully: if a network failure causes the token response to be lost after the server has already invalidated the old token, the client may get into a broken state. Robust implementations include retry logic and fallback to re-authentication. Refresh tokens are typically stored in httpOnly cookies or secure storage (never localStorage) to prevent XSS theft.

For managing token invalidation explicitly, see Token Revocation Flow. The full lifecycle of access tokens is covered in JWT Authentication Flow.

Frequently asked questions

Refresh token rotation is a security pattern where every time a client exchanges a refresh token for new tokens, the authorization server issues a brand-new refresh token and immediately invalidates the old one. This ensures each refresh token can only be used once, unlike simple refresh where the same token is reused indefinitely.

If an attacker steals a refresh token and attempts to use it after the legitimate client has already rotated it, the authorization server detects a reuse of an already-invalidated token. The server responds by revoking the entire token family, forcing re-authentication. This automatic theft detection limits the attacker's window even if interception occurred.

Store refresh tokens in `httpOnly` cookies or secure platform storage — never in `localStorage` where XSS attacks can read them. Keep access token lifetimes short (5–60 minutes). Implement retry logic on the client for network failures during rotation. Use sender-constrained tokens (DPoP) for the highest security. Always associate refresh tokens with a specific client and reject them if the `client_id` does not match.

If the authorization server invalidates the old refresh token but the client never receives the response (network failure), the client will attempt to use the old token again on retry — which now appears as a reuse of an invalidated token. Robust implementations detect this case (e.g., by tracking a grace period for the previous token) and allow a short retry window before triggering revocation.

Refresh token rotation is a proactive security property built into the normal token-refresh cycle: old tokens are invalidated automatically as part of routine operation. Token revocation is an explicit act — calling a revocation endpoint to invalidate a specific token immediately, typically for logout or incident response. Both mechanisms are complementary.

mermaid

sequenceDiagram
    participant Client
    participant AuthServer as Authorization Server
    participant API as Resource Server

    Client->&gt;API: GET /api/data with expired access token
    API-->&gt;Client: 401 Unauthorized - token expired

    Client->&gt;AuthServer: POST /token with refresh_token (RT1)
    AuthServer-->&gt;AuthServer: Validate RT1, check it is not revoked
    alt RT1 valid
        AuthServer-->&gt;AuthServer: Revoke RT1 immediately
        AuthServer-->&gt;AuthServer: Issue new access token + new refresh token RT2
        AuthServer-->&gt;Client: New access token + RT2
        Client->&gt;API: Retry GET /api/data with new access token
        API-->&gt;Client: 200 OK with data
    else RT1 already used (theft detected)
        AuthServer-->&gt;AuthServer: Revoke entire token family
        AuthServer-->&gt;Client: 400 - refresh token reuse detected
        Client-->&gt;Client: Clear all stored tokens
        Client->&gt;Client: Redirect user to login
    else RT1 expired or revoked
        AuthServer-->&gt;Client: 400 - invalid refresh token
        Client->&gt;Client: Redirect user to login
    end