Rotate OAuth Refresh Tokens
Handle OAuth refresh-token replacement, reuse detection, token-family revocation, and client recovery without exposing tokens.
A refresh token lets a client obtain new access tokens after the short-lived one expires. If the same refresh token can be reused indefinitely, a copied value may continue to work. OAuth providers differ in whether they rotate refresh tokens, use sender constraints, or revoke a token family after reuse. Review the provider's actual contract rather than assuming one behavior.
Keep refresh tokens out of model prompts, URLs, and logs. Store them server-side or in a platform store suited to the client type. RFC 9700 says public clients must use sender-constrained refresh tokens or refresh-token rotation to detect replay. Provider implementations still need direct verification. The application needs an atomic way to replace the stored value after a successful refresh.
Token-family state table
| Event | Client state | Required result |
|---|---|---|
| Initial grant | One active refresh token | Store protected reference |
| Successful refresh | New token issued | Replace old value atomically |
| Concurrent refresh | Two requests race | One controlled winner or provider-safe recovery |
| Reuse of old token | Possible compromise | Follow provider family-revocation rule |
| Consent revoked | No active grant | Stop renewal and clear local reference |
A retry after a network timeout is tricky: the provider may have rotated the token while the client missed the response. Do not blindly replay an old token until you know the provider's idempotency or grace behavior. Record the uncertainty and use a reauthorization path when necessary.
Owned integration test
Use a test application and synthetic account. Refresh once and confirm the new token can obtain access. Try the old value only through an authorized safe test to learn whether the provider rejects it. Simulate two concurrent refreshes and a lost response. Check what the application stores and whether it exposes the user to a needless login loop.
Record token identifiers or hashes, not token bytes. Verify that logout or grant revocation ends future refreshes according to the provider's documented timing. A local cache delete does not invalidate a copied refresh token at the authorization server. If family reuse detection is unsupported, document the residual exposure and compensate with shorter lifetime, monitoring, or narrower scopes where possible.
Make offboarding verifiable
Use the offboarding checklist to identify owners, revoke grants and verify the result. Discuss a scoped review of your application's access controls.