OAuth2 Refresh Tokens — Long-Lived Credentials for Continuous API Sessions

In this tutorial, you will learn about OAuth2 Refresh Tokens. We cover key concepts, practical examples, and best practices to help you master this topic.

Refresh tokens are long-lived credentials issued alongside access tokens, allowing clients to obtain new access tokens without requiring the user to re-authenticate.

What You'll Learn

How refresh tokens work, refresh token rotation, when they are issued, and their security characteristics.

Why It Matters

Short-lived access tokens (15-60 minutes) limit damage if stolen. But asking users to log in every hour is impractical. Refresh tokens bridge this gap by enabling silent token renewal.

Real-World Use

Google APIs issue refresh tokens that last until revoked. GitHub supports configurable token expiry. Auth0 uses refresh token rotation for mobile apps.

flowchart LR
    A["Auth Server"] -->|"Access Token (15m)\n+ Refresh Token (30d)"| B["Client"]
    B -->|"API call + Access Token"| C["Resource Server"]
    C -->|"401 Expired"| D["Client"]
    D -->|"Refresh + Refresh Token"| A
    A -->|"New Access + Refresh"| D
    D -->|"New API call"| C
    C -->|"200 OK"| D
    style A fill:#dbeafe,stroke:#2563eb
    style B fill:#fef3c7,stroke:#d97706
    style C fill:#dcfce7,stroke:#16a34a

Access Token vs Refresh Token

Common Mistakes

1. Not Rotating Refresh Tokens

Without rotation, a stolen refresh token is valid until it expires.

2. Storing Refresh Tokens in localStorage

XSS can steal refresh tokens. Use httpOnly cookies or secure device storage.

3. Making Refresh Tokens Permanent

Refresh tokens must expire (7-90 days). Permanent tokens cannot be revoked.

4. Not Handling Refresh Token Rejection

A 401 on refresh may mean the token is revoked. Redirect user to re-authenticate.

5. Sending Refresh Tokens with API Requests

Refresh tokens are only for the token endpoint. Never send them to regular API endpoints.

Practice Questions

1. Why are refresh tokens needed?
2. What is refresh token rotation?
3. How should refresh tokens be stored on the client?
4. What happens when a refresh token expires?
5. How do you detect refresh token theft?

Answers:

1. Access tokens are short-lived for security. Refresh tokens enable long-lived sessions without frequent login.
2. Each refresh returns a new refresh token and invalidates the old one. A stolen token can only be used once.
3. httpOnly cookies (web) or secure device storage/Keychain/Keystore (mobile).
4. The server returns 401 on refresh. The user must re-authenticate.
5. When an already-rotated token is presented, revoke all tokens in the family and alert the user.

Challenge: Implement refresh token rotation with family tracking and theft detection. When an old token is presented after rotation, revoke the entire family.

FAQ

Mini Project

Build a refresh token service with rotation, family tracking, and theft detection. Issue tokens, rotate them, and demonstrate what happens when a stolen token is used.

What's Next

Now learn about the OAuth2 Authorization Server — the core component that issues tokens.