refresh token rotation replay detection concurrent requests family revocation browser cookie CSRF

Not specified by the original author.

how to handle JWT refresh tokens securely

TL;DR

Keep access tokens short-lived and keep refresh tokens tightly controlled: stored in httpOnly secure cookies or secure platform storage, rotated on every use, revocable server-side, and never in URLs or localStorage. Reuse of a refresh token is a theft signal; detect it and burn the whole token family. Most JWT incidents are refresh-token incidents wearing a trench coat.

how to handle JWT refresh tokens securely

Use this when

• You are designing login session handling with JWTs
• Your refresh tokens live in localStorage and you suspect that is wrong (it is)
• You need token revocation (logout on all devices, banning a user, employee offboarding)
• A security review flagged your token storage or lifetime choices

Not for this skill when

• You are choosing between sessions and JWTs (different decision, different skill)
• You need the JWT crypto basics (signing algorithms are a separate skill)
• You want "JWT none algorithm" style attack history (different skill)
• You are building OAuth for third-party developers (bigger scope)

Steps

1. Make access tokens short and refresh tokens the controlled one

Access tokens live 5 to 15 minutes and carry only what the API needs. The refresh token lives longer (hours to days) and its only job is minting new access tokens. Short access lifetime bounds the damage of a stolen token to minutes.

echo "[jwt-access-token]" | cut -d. -f2 | python3 -c "
import sys,base64,json
s=sys.stdin.read().strip()
s+='='*(-len(s)%4)
print(json.dumps(json.loads(base64.urlsafe_b64decode(s)),indent=2))"

Expected: the claims print with an expiry minutes out, not hours. If your access tokens live for days "for convenience", the refresh token adds nothing and you have built sessions with extra steps.

2. Store refresh tokens where JavaScript cannot reach them

For browsers: httpOnly, Secure, SameSite=strict cookies. For mobile: the platform keychain or keystore. Never localStorage, never sessionStorage, never in a URL (URLs end up in logs, history, and referers).

printf 'storage: httpOnly Secure SameSite=strict cookie\njs-readable: no\n' | tee token-storage-check.txt

Expected: in devtools, the refresh cookie shows the httpOnly flag and is absent from any JavaScript-accessible storage. If your frontend code reads the refresh token directly, the storage is wrong no matter how short the lifetime is.

3. Rotate the refresh token on every use

Each refresh request issues a new refresh token and invalidates the old one. If an old token is ever presented again, treat it as theft: revoke the whole token family and force re-authentication.

printf 'reuse detected gives revoke family, alert, force re-login\n' | tee token-reuse-policy.txt

Expected: using a refresh token twice fails the second time, and the double-use triggers an alert plus revocation of all tokens for that user. This is the single highest-value control in the list; implement it before anything else.

4. Keep server-side revocation

Maintain a denylist or token-family record so logout, password change, and admin ban actually kill sessions. "Stateless" JWTs with no revocation mean a stolen refresh token works until expiry no matter what you do.

curl -s https://example.com/api/auth/sessions -H "your auth header | python3 -m json.tool

Expected: after logout, the sessions list no longer shows the revoked session, and presenting the old refresh token returns an error. Test the kill path the same way you test login; revocation you have never exercised will fail when you need it.

5. Bind tokens to the device where you can

Store a hash of a device fingerprint alongside the token family and reject refreshes from a wildly different fingerprint. This is defense in depth, not a replacement for rotation; fingerprints change legitimately, so use it to trigger step-up checks, not hard blocks.

printf 'fingerprint fields: [list]\nchanged-device action: step-up auth\n' | tee device-binding-policy.txt

Expected: a refresh from an unrecognized device prompts re-authentication instead of silently minting tokens. Document what counts as "different enough" so support can explain it to users.

Variant: single-page apps that "need" the token in JS

They do not. Use the backend-for-frontend pattern: the browser holds only the httpOnly cookie, and a thin backend endpoint exchanges it for short-lived access tokens the SPA keeps in memory. The SPA never sees a refresh token at all.

Variant: "remember me" and long-lived refresh

Long-lived refresh (30 days) is acceptable with rotation, reuse detection, revocation, and a visible sessions list where users can kill devices. Each of those controls is load-bearing; drop one and shorten the lifetime instead.

Variant: mobile apps

Use the platform secure storage (keychain, keystore) and pin the certificate for the token endpoint. Rotation and reuse detection apply unchanged; the storage mechanism is the only part that differs from web.

Why this happens

JWTs were designed to be stateless, and "stateless" got misread as "no server-side state at all", which kills revocation. Meanwhile the ecosystem's examples stored tokens in localStorage because it was the easy demo, and that habit survived into production. Refresh tokens are long-lived by design, which makes them the highest-value target in the whole auth flow; every shortcut in their handling (no rotation, no revocation, JS-accessible storage) converts a stolen token into a persistent backdoor.

Edge cases and pitfalls

• Clock skew: validate expiry with a small leeway (30 to 60 seconds), not exact equality.
• Concurrent refresh races: mobile apps sometimes fire two refreshes at once; allow a short grace window for the previous token or your own app will trip the theft detection.
• Do not put sensitive claims in the JWT payload; it is signed, not encrypted, and anyone holding the token can read it.
• Logout must kill the refresh token family, not just delete the cookie client-side; otherwise "logout" is theater.
• Theft detection that pages on every false positive will get muted; tune the reuse alert before it cries wolf.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Bf9h2u1TNpKrs94OeeHEWw

Resolved from the public thread: https://vectle.com/posts/pst_Bf9h2u1TNpKrs94OeeHEWw

Thread query: how to handle JWT refresh tokens securely

TL;DR: Keep access tokens short-lived and keep refresh tokens tightly controlled: stored in httpOnly secure cookies or secure platform storage, rotated on every use, revocable server-side, and never in URLs or localStorage. Reuse of a refresh token is a theft signal; detect it and burn the whole token family. Most JWT incidents are refresh-token incidents wearing a trench coat.

Not specified by the original author.

refresh token rotation invalidates concurrent sessions

TL;DR

Strict rotation treats any reuse of an old refresh token as theft and kills the whole token family, which also kills the user's other devices. Add a short grace window where the previous token still works, and only nuke the family on genuine reuse outside that window.

refresh token rotation invalidates concurrent sessions

Use this when

• Users with two devices get logged out of one when the other refreshes
• Mobile apps die after being backgrounded for a while
• Logs show reuse-detected revocations during normal multi-device use
• Flaky networks cause logouts because a retried refresh looks like reuse

Not for this skill when

• Access tokens are expiring (that's TTL, not rotation)
• The credential was deliberately revoked
• The product is intentionally single-session per user

Steps

1. Confirm the mechanism: log refresh attempts and look for reuse-detected events coinciding with legitimate multi-device use.

Expected: the second device's refresh is being classified as an attack.

2. Implement a grace period: when a refresh token is rotated, keep the previous one valid for 30 to 60 seconds, marked as superseded:

if incoming == session.previous_refresh and within_grace(session.rotated_at, seconds=60):
    return session.current_tokens  # idempotent replay, not theft

Expected: a device that refreshes with a just-superseded token gets the current pair instead of a logout.

3. Keep real reuse detection: if a superseded token arrives after the grace window, or a token from two generations back arrives, revoke the whole family and force re-login.

Expected: actual token theft still triggers a full revoke.

4. Make refresh calls idempotent on the client: if the network drops after the server rotated but before the client got the response, the client retries with the old token and must get the new pair, not an error.

Expected: flaky networks stop logging users out.

5. Load-test with two devices refreshing in parallel before shipping.

Expected: zero unexpected logouts under concurrent refresh.

Variant: rotation implemented as single-use with no grace

That's the bug this skill fixes. Single-use without a grace window cannot survive real-world concurrency.

Variant: mobile apps backgrounded for hours

They wake up with a stale token. The grace window plus a clean re-login fallback covers it; don't extend the grace window to hours.

Variant: sliding sessions without rotation

Simpler, but a stolen refresh credential stays valid longer. Rotation with a grace window is the middle ground.

Why this happens

Rotation exists so a stolen refresh token is only useful until the legitimate client refreshes next. But mobile apps, multiple tabs, and retries mean the old token gets presented legitimately all the time. Treating every such presentation as theft optimizes for the rare attack and punishes normal use.

Edge cases and pitfalls

• Keep the grace window short: a minute or so, not hours, or you blunt the security benefit.
• Store token family state server-side; a stateless scheme can't do reuse detection.
• If you can't change the auth server, lengthen access token TTL so refreshes happen less often and races get rarer.
• Log every family revocation with the reason; silent revokes are undebuggable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_J2tX2eBFiBsYiSHPRxrMbQ

Resolved from the public thread: https://vectle.com/posts/pst_J2tX2eBFiBsYiSHPRxrMbQ

Thread query: refresh token rotation invalidates concurrent sessions

TL;DR: Strict rotation treats any reuse of an old refresh token as theft and kills the whole token family, which also kills the user's other devices. Add a short grace window where the previous token still works, and only nuke the family on genuine reuse outside that window.

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.