Refresh token rotation is a token lifecycle pattern where each successful refresh issues a new refresh token and invalidates the previous one.
The goal is to reduce the damage caused by a stolen refresh token.
Quick answer
Without rotation, a stolen refresh token may work until it expires or is revoked.
With rotation, the backend replaces the refresh token every time it is used. If an old token is used again, the backend can treat that as suspicious reuse and revoke the token family.
Refresh token rotation is most useful when refresh tokens are long-lived, high-value, or used by public clients such as browser and mobile apps.
Access tokens vs refresh tokens
Access tokens are used to call APIs. They should usually be short-lived.
Refresh tokens are used to obtain new access tokens. They should be sent only to the token endpoint or refresh endpoint.
Read Access Token vs Refresh Token for the broader comparison.
The basic refresh flow:
1. Client sends refresh token to token endpoint.
2. Server validates the refresh token.
3. Server issues a new access token.
4. Server may issue a new refresh token.
5. Server invalidates the previous refresh token.Step 4 and step 5 are the rotation part.
Why rotation helps
A static refresh token is powerful. If it leaks, an attacker may keep minting access tokens.
Rotation makes token theft easier to detect.
Suppose a legitimate client uses refresh token R1 and receives R2. If an attacker later tries to use R1, the server can detect reuse.
That reuse signal does not always prove exactly what happened, but it is serious enough to revoke the token family, require login again, or notify the user.
Token families
Refresh token rotation often uses the idea of a token family.
A token family represents a chain of refresh tokens created from the same login or authorization grant.
Example:
R1 -> R2 -> R3 -> R4Only the latest token should be active. Older tokens should be invalid after rotation.
If the backend sees an older token again, it may revoke the whole family:
R1 -> R2 -> R3 -> R4
reuse detected for R2
revoke family
force reauthenticationThis is more useful than revoking only the old token that was already supposed to be invalid.
Storage model
Backend storage should track enough metadata to validate and rotate safely.
Useful fields:
| Field | Purpose |
|---|---|
| Token hash | Avoid storing raw refresh tokens. |
| Family ID | Connect tokens from the same login or grant. |
| User or subject | Know who the token belongs to. |
| Client ID | Know which app received it. |
| Issued time | Support auditing and expiration. |
| Expiration | Limit maximum lifetime. |
| Previous token status | Detect reuse. |
| Revoked time and reason | Support incident response. |
As with API keys, avoid storing raw token secrets if you can store a safe hash.
Read API Key Design Best Practices for similar storage and redaction ideas.
Race conditions and retries
Refresh token rotation can create race conditions.
For example, a mobile app might send two refresh requests close together because of retry behavior or parallel API calls. The first request rotates the token. The second request uses the now-old token.
If the backend treats every old-token use as theft, legitimate users may be logged out too often.
Common mitigations include:
- Synchronizing refresh calls on the client.
- Short grace windows for immediate duplicate requests.
- Idempotent refresh handling for the same request.
- Careful logging and risk scoring.
- Clear retry behavior for token endpoints.
Do not ignore reuse detection entirely, but design for real network behavior.
Logout and revocation
Refresh token rotation should connect to logout, password changes, MFA changes, account disablement, and suspicious activity.
Important events may revoke:
- One refresh token.
- One device or session.
- One token family.
- All tokens for a user.
- All tokens for an organization or compromised client.
The right scope depends on risk.
For a password reset, revoking active refresh token families is often safer. For a normal logout on one device, revoking only that device’s family may be enough.
Read MFA Explained for Web Apps for step-up and recovery flows that may affect token trust.
Common mistakes
The first mistake is using refresh tokens as normal API bearer tokens.
The second mistake is making refresh tokens long-lived without rotation, revocation, or reuse detection.
The third mistake is storing raw refresh tokens in logs or databases.
The fourth mistake is not handling parallel refresh requests.
The fifth mistake is revoking only one old token after reuse when the whole token family may be compromised.
The sixth mistake is not documenting token lifetime, idle timeout, maximum lifetime, and logout behavior for clients.
Practical recommendation
For high-value applications, use short-lived access tokens and rotate refresh tokens.
A practical backend design:
- Store refresh token hashes.
- Track token family IDs.
- Rotate on every successful refresh.
- Invalidate the previous token.
- Detect reuse of old tokens.
- Revoke the token family on suspicious reuse.
- Handle immediate duplicate refresh attempts carefully.
- Redact tokens from logs and traces.
- Document refresh, logout, and revocation behavior.
Refresh token rotation is not free. It adds storage, state, and edge cases. But for many OAuth and session-like API systems, that complexity buys meaningful risk reduction.
Related reading
Read Access Token vs Refresh Token first, then read JWT Claims Explained for expiration, subject, audience, issuer, and token validation details.
For adjacent authentication risks, read JWT vs Session Authentication, MFA Explained for Web Apps, and Session Fixation Explained. For the full security sequence, browse the Backend Security Learning Path and the Topics map.