Refresh Token

How it works

An OAuth 2.0 or OIDC token exchange issues two tokens: a short-lived access token (typically 5 to 60 minutes) that the API accepts, and a refresh token (days to months) that the client presents to the authorization server's token endpoint to get a new access token without the user logging in again. The refresh token is opaque to the resource server, it only means anything at the token endpoint. Best practice for public clients (SPAs, mobile apps) is refresh token rotation: every use issues a brand new refresh token and invalidates the old one, so a stolen-and-reused token gets detected the moment the legitimate client tries to use its (now revoked) copy.

When it matters

Once your access tokens expire in under an hour, which they should, you need refresh tokens to avoid forcing users back through the login screen every 15 minutes. It matters most for OAuth 2.0 and OIDC flows in single-page apps and mobile clients, where there's no server-side session to fall back on. Skip the complexity if you're running a traditional server-rendered app with cookie sessions, you don't need OAuth refresh semantics at all in that case.

Common misconceptions

• "A refresh token is just a longer-lived access token." It isn't accepted by APIs directly, it's only redeemable at the token endpoint for a new access token.
• "Rotation is optional for single-page apps." It's the main defense against a stolen refresh token being replayed indefinitely; without rotation, one XSS-leaked token is a permanent backdoor.
• "Refresh tokens belong in localStorage next to the access token." localStorage is readable by any script on the page. Store refresh tokens in an httpOnly, secure cookie or platform keychain, never in JS-accessible storage.