Session token refresh flow
Access token expiry, refresh token exchange, and silent re-authentication.
Session management using access and refresh tokens is the industry standard for stateless authentication. The client gets a short-lived access token (5–15 minutes) for API requests and a long-lived refresh token (days) used only to silently obtain new access tokens. When the access token expires, the client calls the refresh endpoint with the refresh token and gets a fresh access token without asking the user to log in again.
This template shows the happy path (user calls API, token valid, request succeeds) and the recovery path (token expires, client refreshes silently, retries the original request). It also shows logout and token revocation. The sequence makes visible where each token lives and the order of validation checks (is the refresh token still valid? has it been revoked?).
When to use this template
- Auth system design — lock down token expiry, storage, and rotation strategies with your security team before writing login and refresh endpoints. The diagram makes the invariants explicit.
- Frontend interceptor implementation — use this to guide your HTTP client layer, so every endpoint can transparently handle 401 and refresh without duplicating logic in every component.
- Security audit — show auditors how you handle token expiry, revocation, and refresh, and where each token is stored (access token in memory, refresh token in httpOnly cookie) so attackers can't steal it via XSS.
How to adapt it
Layer in your real infrastructure:
- Add two-factor authentication as an extra step after login, before tokens are issued, or requiring re-auth for sensitive operations.
- Insert token rotation between Refresh and Return: each refresh request returns a new refresh token and invalidates the old one, limiting the window if a refresh token is leaked.
- Extend the revocation path: when a user changes their password or signs out from all devices, revoke all refresh tokens for that user, not just the current one.
Visual edits regenerate clean Mermaid code, so you can sketch your token lifecycle and share it with your backend and frontend teams.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
actor User
participant Client as Client App
participant Gateway as API Gateway
participant Auth as Auth Service
participant API as Protected API
User->>Client: Use app
Client->>API: Call endpoint + access_token
API-->>Client: 200 OK (token valid)
Note over Client: 15 min later...
Client->>API: Call endpoint + access_token (expired)
API-->>Client: 401 Unauthorized
Client->>Auth: POST /refresh + refresh_token
Auth->>Auth: Validate refresh_token
Auth-->>Client: 200 OK + new access_token
Client->>API: Retry with new access_token
API-->>Client: 200 OK
Note over Client: User closes app
User->>Client: Sign out
Client->>Auth: POST /logout + refresh_token
Auth->>Auth: Revoke refresh_token
Auth-->>Client: 200 OK
Frequently asked questions
- What is the difference between access tokens and refresh tokens?
- An access token is a short-lived credential (5-15 minutes) that grants access to protected resources. A refresh token is long-lived (days or weeks) and is used only to request new access tokens. If an access token is stolen, the damage is limited to that window. If a refresh token is stolen, an attacker can request new access tokens indefinitely — so refresh tokens are stored securely (httpOnly cookies, encrypted storage) and never sent to the frontend over HTTP.
- Why does the access token expire?
- Short expiry (5-15 min) limits the window of exposure if a token is stolen or leaked. If an attacker steals a token, they can impersonate the user only until it expires. The refresh token flow lets legitimate users silently get new access tokens without re-entering their password, while invalidating stolen tokens within minutes. This is the balance between security (short expiry) and user experience (silent re-authentication).
- What happens if both tokens are stolen?
- If an attacker steals both the access token and the refresh token, they can request new access tokens indefinitely and impersonate the user. Mitigate by: storing refresh tokens securely (httpOnly, sameSite cookies), using token rotation (each refresh request returns a new refresh token, invalidating the old one), rotating keys frequently, and monitoring for suspicious refresh patterns (e.g., multiple refresh requests from different IPs). Revoke tokens immediately if a breach is detected.
- How do I implement silent re-authentication on the frontend?
- When an API call returns 401, intercept it in the HTTP client layer (fetch interceptor, axios interceptor) and automatically call POST /refresh to get a new access token. Retry the original request with the new token. If refresh fails (e.g., the refresh token expired or was revoked), redirect the user to login. Visual edits regenerate the sequence diagram, so you can sketch your token flow and share it with your backend team to align on expiry, storage, and rotation strategies.