Prompt
OAuth refresh token storage
Latest observation
Oct 16, 2026
OpenAI APIWeb search: off
OAuth refresh tokens are high-value secrets. The main goal is to reduce exposure, limit blast radius, and make theft less useful.
Best practices
1) Prefer not storing refresh tokens unless you must
- If your app can use short-lived access tokens only, do that.
- For web apps, consider server-side session management instead of exposing refresh tokens to the browser.
2) Keep refresh tokens server-side
- Never store refresh tokens in client-side JavaScript-accessible storage like:
localStoragesessionStorage- plain browser cookies without
HttpOnly
- Store them on the backend in a database or secrets store.
3) Encrypt tokens at rest
- Use strong encryption before saving to a DB.
- Protect encryption keys separately, ideally in:
- KMS/HSM
- cloud secret manager
- dedicated key management service
- Rotate keys when possible.
4) Use least-privilege access
- Only the service that needs the token should be able to read it.
- Restrict DB/secret-store access tightly.
- Audit access to token records.
5) Use refresh token rotation
- Prefer providers that support rotating refresh tokens.
- Each refresh returns a new refresh token; old ones become invalid.
- This reduces damage if one token leaks.
6) Bind tokens to a user/session/device where possible
- Use sender-constrained or proof-of-possession mechanisms if available:
- DPoP
- mTLS
- This helps prevent reuse if stolen.
7) Store metadata, not just the token
Useful fields:
- user/account ID
- provider
- scope
- issued-at / expires-at
- token family or rotation chain ID
- last-used timestamp
- status/revoked flag
8) Handle revocation and expiration
- Support explicit revocation on logout, password reset, or account disconnect.
- Detect invalid_grant / token reuse and force re-authentication.
9) Never log tokens
- Redact tokens from:
- application logs
- error traces
- analytics
- support tickets
- Watch out for debug dumps and HTTP request logging.
10) Minimize token lifetime and scope
- Ask for only the scopes you need.
- Use short-lived access tokens, with refresh only when necessary.
- Prefer incremental authorization over broad initial scopes.
Common storage patterns
Backend web app
- Store refresh token in encrypted DB record.
- User session cookie:
HttpOnly,Secure,SameSite=Lax/Strict. - Browser never sees refresh token.
Mobile app
- Store in OS secure storage:
- iOS Keychain
- Android Keystore/EncryptedSharedPreferences
- Avoid plaintext app storage.
Desktop app
- Use OS credential vaults:
- macOS Keychain
- Windows Credential Manager
- Linux secret service if available
What not to do
- Don’t put refresh tokens in:
- URLs
- localStorage
- plain config files
- source code
- shared spreadsheets or docs
- Don’t reuse the same refresh token across unrelated environments.
Recommended secure pattern
- User authenticates with OAuth.
- Backend receives authorization code.
- Backend exchanges code for access + refresh token.
- Backend encrypts and stores refresh token.
- Backend uses refresh token only when access token expires.
- Backend rotates and revokes as needed.
If you want, I can give you:
- a database schema for secure refresh token storage,
- a Node/Python/Go example, or
- guidance for SPA vs backend web app storage.