Refresh Tokens: Persistent Sessions Without Re-Authentication

WHY IT EXISTS: Sending a user's password with every request is a massive security risk. Even sending a long-lived access token is risky; if stolen, it grants access for a long time. We need a way to keep users logged in without exposing powerful, long-lived credentials on every API call, while still minimizing the attack surface of any single credential.

THE MENTAL MODEL: Think of an access token as a day pass to an amusement park, and a refresh token as your season pass ID card. You show the day pass at every ride. When it expires at the end of the day, you don't drive home and re-apply for a new pass. Instead, you go to the main office, show your season pass ID, and they give you a new day pass. The season pass ID is used rarely and kept securely in your wallet, while the day pass is used frequently and is less of a disaster if lost.

HOW IT WORKS: During the initial login, the authorization server gives the client both a short-lived access token (e.g., expires in 15 minutes) and a long-lived refresh token (e.g., expires in 30 days). The client uses the access token for all API requests. When the access token expires, the client gets a 401 Unauthorized error. The client then makes a special request to a token endpoint, presenting its refresh token. If the refresh token is valid and not revoked, the server issues a new access token (and sometimes a new refresh token). The client can then resume making API calls.

WHEN TO USE IT: Use refresh tokens for any client application, like web frontends or mobile apps, where you want to maintain a user's session beyond a few minutes without forcing them to log in again. This is the standard for user-facing applications that need persistent login sessions.

WHEN NOT TO USE IT: Do not use refresh tokens in environments where they cannot be stored securely. For public clients like single-page applications (SPAs), storing refresh tokens in browser localStorage is a major footgun as it's vulnerable to XSS attacks. In these cases, storing the refresh token in a secure, HttpOnly cookie is the recommended approach. For machine-to-machine communication, the client credentials flow is often a better fit.

ONE CANONICAL EXAMPLE: A user logs into their banking mobile app. The app receives an access token (valid for 10 minutes) and a refresh token (valid for 90 days). The user checks their balance and makes transfers, with each action authenticated by the access token. The next day, they open the app. The app detects the old access token is expired, silently uses the stored refresh token to get a new access token from the bank's server, and then loads the user's account data. The user never had to re-enter their password.