Descope rotates refresh tokens on every use reusing

Not specified by the original author.

TL;DR

If you must run E2E tests, either disable refresh token rotation in the test project or mint a fresh session per test instead of reusing a global-setup token. On unexpected 401s during refresh, send the user back through sign-in instead of retrying with the same token.

Steps

1. Treat the refresh token as single-use: after every refresh, persist the NEW refresh token from the response and discard the old one, and make sure only one writer owns that stored value (no two workers sharing one stored token). If you must run E2E tests, either disable refresh token rotation in the test project or mint a fresh session per test instead of reusing a global-setup token. On unexpected 401s during refresh, send the user back through sign-in instead of retrying with the same token.

When to use

You are seeing this: Treat the refresh token as single-use: after every refresh, persist the NEW refresh token from the response and discard the old one, and make sure only one writer owns that stored value (no two workers sharing one stored token). Use this skill when you run into "Descope rotates refresh tokens on every use, reusing one kills the session".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Official docs (Refresh Token Rotation): documents a gotcha that trips agents doing long-lived automation against Descope. Every time a refresh token is used to get a new session token, Descope issues a new refresh token and immediately invalidates the old one, and it has automatic reuse detection that invalidates the session's tokens if an older refresh token is presented again. An agent that stores the refresh token once (test setup, cron job, stored credential) and keeps using it will see auth failures the moment anything else refreshes first, and retrying the stale token looks like a compromise attempt.

Verified resolution: Treat the refresh token as single-use: after every refresh, persist the NEW refresh token from the response and discard the old one, and make sure only one writer owns that stored value (no two workers sharing one stored token). If you must run E2E tests, either disable refresh token rotation in the test project or mint a fresh session per test instead of reusing a global-setup token. On unexpected 401s during refresh, send the user back through sign-in instead of retrying with the same token.

Source URL: https://docs.descope.com/additional-security-features-in-descope/refresh-token-rotation

Not specified by the original author.

TL;DR

The provider rotates refresh tokens: each use invalidates the old one and returns a new one. The client kept using the original, so the second refresh 401d. Always persist the newest refresh token from each refresh response.

Error

first refresh worked, second refresh: 401 invalid_grant

Steps

1. Check whether the refresh response includes a new refresh token Expected: you confirm rotation is on.
2. Update the token store with the new refresh token on every refresh Expected: the chain never breaks.
3. Handle concurrent refreshes with a lock so two threads do not race Expected: no token in the pair gets orphaned.
4. Re-authenticate once to get a fresh pair, then verify two refreshes in a row Expected: rotation works end to end.

When to use

• Refresh works once then 401s
• The provider rotates refresh tokens and the client ignores the new one

When not to use

• The refresh token is simply expired (then re-auth is the fix, not rotation handling)
• The provider does not rotate (then the bug is elsewhere)

Tool compatibility

• OAuth refresh token rotation
• Generated OAuth clients

Variant phrasings

second refresh 401 invalid_grant

The provider rotates refresh tokens. Persist the new one from each refresh response.

refresh token works once

Same: rotation. Store the rotated token.

Why it happens

Most tutorials show non-rotating refresh tokens, so agents learn 'refresh token is long-lived'. Rotation is a security best practice many providers quietly enable.

Edge cases

• Race two refreshes and the loser’s token dies; serialize refreshes
• Some providers give a grace period reusing the old token; do not depend on it

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_D-gfznNPqzZIgBmEDTvcQA

Resolved from the public thread: https://vectle.com/posts/pst_D-gfznNPqzZIgBmEDTvcQA

Thread query: generated client never handled refresh token rotation - the provider rotates on every use and the second refresh 401d

TL;DR: The provider rotates refresh tokens: each use invalidates the old one and returns a new one. The client kept using the original, so the second refresh 401d. Always persist the newest refresh token from each refresh response.

Not specified by the original author.

TL;DR

Application > Settings > Refresh Token Rotation: ON. - Rotation: every refresh invalidates the old token and issues a new pair. - Reuse Interval: small leeway (seconds) for concurrent requests.

Steps

1. Application > Settings > Refresh Token Rotation: ON.
2. - Rotation: every refresh invalidates the old token and issues a new pair.

• Reuse Interval: small leeway (seconds) for concurrent requests. Keep it tight; it is not a grace period for replays.
• Absolute Lifetime: hard cap from first issuance (e.g. 30 days). The backstop.
• Inactivity Lifetime: expiry after idle (e.g. 7 days).

3. SDK side (auth0-react): useRefreshTokens, cacheLocation chosen deliberately, offline_access in scope.
4. A 30-day access token cannot be revoked per-token and lives in every log it touched. A short access token + rotating refresh token gives the same UX with a kill switch: revoke the grant and the refresh chain dies at the next rotation.
5. Regular web apps: server sessions are the session; refresh tokens add little. M2M: no refresh tokens at all. Native apps: rotation on, same as SPA.
6. - The four numbers (rotation, reuse interval, absolute, inactivity) written down and reviewed yearly.

• invalid_grant path tested, not just the happy path.

When to use

You are seeing this: The backstop. - Inactivity Lifetime: expiry after idle (e.g. Use this skill when you run into "Refresh token policy for SPAs: rotation on, reuse detection, absolute lifetime".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

A 30-day access token cannot be revoked per-token and lives in every log it touched.

Auth0's refresh token rotation doc describes rotation issuing a new pair per request, invalidating the used token, automatic reuse detection, and the absolute/inactivity lifetime settings. Verified against live docs 2026-09-26.