What Is a Refresh Token?

A Refresh Token is a credential used to obtain a new access token without requiring the user to log in again. While access tokens are typically short-lived and expire quickly for security reasons, refresh tokens are longer-lived and provide a mechanism to extend the user session seamlessly.

They are an essential part of OAuth 2.0 and modern web authentication architectures, especially in systems where stateless access tokens are used and user experience matters.

Why Are Refresh Tokens Important?

Access tokens are often designed to expire quickly (e.g., 15 minutes) to minimize the damage of token theft. However, asking users to log in every 15 minutes would be frustrating. Refresh tokens solve this by allowing the application to silently obtain a new access token in the background.

This provides a balance between:

  • Security (short-lived access tokens)
  • Usability (persistent sessions without repeated logins)

How Does a Refresh Token Work?

Here is a high-level overview of how refresh tokens are used:

  1. The client application sends the user’s credentials to the authentication server.
  2. If authentication succeeds, the server returns:
    • An access token (short-lived)
    • A refresh token (long-lived)
  3. The client uses the access token to call APIs.
  4. When the access token expires, the client sends the refresh token to get a new access token.
  5. The server validates the refresh token and, if valid, returns a new access token.

Sample Token Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "refresh_token": "d9d3f28a-b142-4b95-9b4f...",
  "expires_in": 900,
  "token_type": "Bearer"
}

Refresh Token vs Access Token

FeatureAccess TokenRefresh Token
PurposeAccess protected resourcesGet new access tokens
ExpirationShort (minutes)Long (hours or days)
Sent With RequestsYes, in Authorization headerNo, only sent to auth server
Stored On ClientYesYes (more securely)
Should Be Encrypted?OptionalRecommended

How to Use a Refresh Token (Example)

Suppose your access token expires after 15 minutes. When the API returns a 401 Unauthorized, you can send a refresh request like this:

POST /auth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "d9d3f28a-b142-4b95-9b4f..."
}

The authentication server returns a new access token and optionally a new refresh token.

Where Should You Store Refresh Tokens?

Due to their longer lifespan and potential security risks if compromised, refresh tokens should be stored more securely than access tokens.

Recommended storage methods:

  • Mobile Apps: Use secure device storage (Keychain on iOS, Keystore on Android)
  • Browser-Based Apps:
    • Prefer HTTP-only, Secure cookies with SameSite=strict
    • Avoid storing refresh tokens in localStorage or sessionStorage
  • Server-Side Apps: Store refresh tokens in encrypted databases or memory-safe caches

When Should a Refresh Token Expire?

There is no standard expiration duration, but some best practices include:

  • Short-Lived: A few hours (forces frequent re-issuance)
  • Long-Lived: Days or weeks (better UX, higher risk if stolen)
  • Rotating: Issue a new refresh token each time it’s used, and revoke the old one.

Rotating Refresh Tokens

Rotating refresh tokens increase security by limiting replay attacks. Here’s how it works:

  1. The client uses a refresh token to get a new access token and a new refresh token.
  2. The server invalidates the old refresh token immediately.
  3. If a previously used refresh token is sent again, the server rejects it.

This pattern protects against a stolen refresh token being used repeatedly.

Revoking Refresh Tokens

To allow users to log out or invalidate sessions, the server must be able to revoke refresh tokens. This is usually done by storing them in a database with:

  • User ID
  • Expiration
  • Revocation status

When a user logs out, the token is flagged as revoked and rejected on the next use.

Common Security Mistakes to Avoid

  • Storing refresh tokens in localStorage
  • Sending tokens over unencrypted HTTP
  • Using refresh tokens in public clients without backend
  • Not rotating tokens after use
  • Not implementing a logout mechanism

Real-World Use Case: Google OAuth 2.0

Google’s OAuth 2.0 implementation uses refresh tokens to keep users signed into services like Gmail or Google Calendar. After initial consent, refresh tokens let Google apps access data without prompting the user to log in every time.

For security, Google applies scopes, expiration limits, and usage thresholds. If the refresh token isn’t used for a while, it becomes invalid, requiring user re-authentication.

Summary: When to Use Refresh Tokens

Use refresh tokens if:

  • You’re using short-lived access tokens for security.
  • You want to avoid re-authentication every few minutes.
  • Your app is long-running (e.g., mobile or desktop).
  • You have a secure way to store tokens.

Avoid them if:

  • Your app is very short-lived (e.g., CLI tool).
  • You can’t securely store the token.

Internal Links for Further Reading

External References

Related Keywords

Access Token
API Security
Authorization Server
Bearer Token
JWT Token
OAuth 2.0
Refresh Token
Rotating Token
Secure Storage
Token Expiration
Token Revocation
Token Rotation
Token Storage
Web Authentication