Refresh Token

Pronunciation: ri-FRESH TOH-kun

Updated October 3, 20262 min read

In short

A refresh token is a long-lived credential an app uses to get new short-lived access tokens, so the user stays signed in without logging in again.

What is a refresh token?

Access tokens are sent with every API request, so they are kept short-lived, often five to sixty minutes, to limit the damage if one leaks. Logging in again every hour would be unbearable, so at login the server also issues a refresh token. When the access token expires, the app sends the refresh token to the token endpoint and receives a fresh access token.

Because refresh tokens are powerful and long-lived, they need more protection than access tokens. They are only ever sent to the authorization server, never to ordinary APIs. In browsers they are best kept in httpOnly, secure cookies that scripts can't read; on mobile, in the system keychain. Servers can revoke them, for example when the user logs out or changes their password.

Refresh token rotation adds another safeguard: each use returns a new refresh token and invalidates the old one. If a stolen token is used after the real app has already rotated it, the server sees the reuse, revokes the whole chain and forces a new login. Many identity providers also limit a refresh token's total lifetime and inactivity period.

A common misconception is that a refresh token is just a long-lasting access token. It is a different credential with a different audience: APIs should reject it, and it should never be stored in localStorage, where any injected script could steal it.

Key takeaways

Refresh tokens get new access tokens without a new login.
Access tokens stay short-lived to limit damage if they leak.
Refresh tokens go only to the token endpoint and need strong protection.
Rotation issues a new refresh token on each use and detects reuse.
Keep them in httpOnly cookies or the keychain, never localStorage.

Example

Refreshing an access token when it expiresjavascript

async function apiFetch(url, options = {}) {
  let response = await fetch(url, { ...options, credentials: "include" });

  if (response.status === 401) {
    // The access token expired: ask the auth server for a new one.
    // The refresh token travels in an httpOnly cookie the script can't read.
    const refreshed = await fetch("/auth/refresh", { method: "POST", credentials: "include" });
    if (!refreshed.ok) {
      window.location.assign("/login");        // refresh token expired or revoked
      return;
    }
    response = await fetch(url, { ...options, credentials: "include" });   // retry once
  }
  return response;
}

Readers ask

What is the difference between an access token and a refresh token?

An access token is sent to APIs to prove what the caller may do and expires quickly. A refresh token is sent only to the authorization server to get new access tokens and lasts much longer.

Where should refresh tokens be stored?

In web apps, in a secure, httpOnly, SameSite cookie, or entirely on a backend server. In mobile apps, in the platform's secure storage such as the iOS Keychain or Android Keystore.

What is refresh token rotation?

Issuing a new refresh token every time one is used and invalidating the old one. If an old token shows up again, the server knows it was stolen and revokes the session.