OAuth token refresh flow
Exchange refresh tokens for new access tokens when the old ones expire.
Modern authentication is stateless: instead of storing sessions on the server, the client holds a credential (the access token) that proves identity to the resource server. But access tokens are time-limited — they expire — and re-authenticating the user every time is a poor experience. The refresh token pattern solves this: the client exchanges an expired access token for a new one using a longer-lived refresh token, all without user interaction.
This sequence shows the happy path: the client requests a resource, gets a 401 because the access token has expired, exchanges the refresh token with the auth server for a new pair, and retries the request. The auth server validates the refresh token's signature and freshness, checks that it hasn't been revoked, and hands back new tokens.
When to use this template
- OAuth/OIDC implementation — document the token refresh loop for engineers integrating your auth server or for consumers of your API.
- Security review — walk through where refresh tokens are stored (secure storage or HTTP-only cookie?), how they are rotated, and what signals revoke them (logout, suspicious activity, time limit exceeded).
- Client library design — build a diagram of when your SDK should transparently refresh tokens and when it should fail fast, so it matches your resource servers' error handling.
How to adapt it
Extend the diagram to match your implementation:
- Add a token revocation check in the auth server step (does the refresh token appear in a revocation list or bloom filter?).
- Insert a key rotation step if your auth server rotates signing keys — the client may need to fetch a new public key if it gets a signature error.
- Add a parallel rate-limit or replay check off the auth server to detect refresh-token abuse (same token used from many clients, too-frequent refreshes).
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant Client
participant AuthServer
participant ResourceServer
Client->>ResourceServer: API request + access_token
ResourceServer-->>Client: 401 Unauthorized (expired)
Client->>AuthServer: POST /token refresh_token=...
AuthServer->>AuthServer: Validate refresh token
AuthServer-->>Client: access_token + refresh_token
Client->>ResourceServer: API request + new access_token
ResourceServer-->>Client: 200 OK + data
Frequently asked questions
- What is an OAuth token refresh flow?
- When an access token expires, the client exchanges a long-lived refresh token for a fresh access token without asking the user to log in again. The auth server validates the refresh token, revokes old tokens if needed, and hands back new ones. This pattern keeps users signed in while restricting the lifetime of any single access token.
- Why not just use long-lived access tokens?
- If an access token is stolen, a short lifetime limits the window of exposure. Refresh tokens are stored more securely — often in HTTP-only cookies or encrypted storage — so they can live longer. Separating short-lived access tokens from long-lived refresh tokens is the OAuth2 / OIDC standard.
- What happens if the refresh token expires or is revoked?
- The auth server rejects the refresh request (401 or 403), and the client must send the user back to the login page. This is a sign of inactivity or account tampering. Some apps show a 'Your session has expired, please log in again' message; others silently redirect to login.
- Can I track token usage for audit or abuse detection?
- Yes. Log every token issuance in an audit table with client_id, user_id, timestamp, and IP address. In the auth server, reject refresh requests from unusual IPs or patterns (e.g. same refresh token used from 3 continents in 10 seconds), and alert the user if their account is compromised. This is how major OAuth providers detect account takeover.