Refresh Tokens and Rotation

You've built a FastAPI app with access tokens, but soon you realize the token expires, and your users are constantly forced to log in again. Or worse, you set a long expiry to avoid that, and a stolen token becomes a long-lived security hole. This lesson solves that pain by introducing refresh tokens and rotation — a strategy that keeps sessions alive seamlessly while shrinking the window in which a leaked access token is dangerous. Let's implement it in FastAPI, step by step.

The problem this lesson solves

Short access tokens are safer, but they force users to re-authenticate constantly. Long access tokens are convenient, but they turn a single stolen token into an open door. The classic compromise — a short-lived access token (e.g., 15 minutes) plus a longer-lived refresh token (e.g., 7 days) — only works if you also protect the refresh token from reuse.

If an attacker steals a refresh token, and your app accepts it forever, the damage is huge. Refresh token rotation means every time a client uses a refresh token, you issue a new one and invalidate the old. That way, a stolen token is useless after its first use, and you can even detect a theft when the same token is reused.

Key pain points this lesson fixes:

• Users logging in too often because access tokens expire too quickly.
• Security holes from long-lived access tokens.
• Stolen refresh tokens being replayed endlessly.
• No way to log out all sessions for a user (common problem with pure JWT).

Core concept / mental model

Think of an access token as a hotel key card for your room. It expires after a short time (like checkout time) to limit damage if lost. A refresh token is the hotel's main desk — you present it to get a new key card without re-verifying your identity. Rotation is like the hotel updating your room number every time you get a new key card; the old key card becomes invalid.

In JWT terms, both tokens are signed JSON web tokens. The access token contains the user ID and claims, and is verified by any service without touching the database. The refresh token is stored server-side (e.g., in a database or Redis) with a random jti (JWT ID) so you can revoke it.

Definitions:

• Access token: short-lived (minutes), stateless, used to authorize API calls.
• Refresh token: longer-lived (days), stateful, used only at the token endpoint to get a new access token.
• Rotation: each refresh request returns a new access token AND a new refresh token; the old refresh token is invalidated.

Here's a mental diagram in words:

Client --(login)--> Server
   <-- access + refresh (refresh saved in DB)

Client --(API call with access token)--> Server (validates JWT)

When access expires:
Client --(refresh token)--> /auth/refresh
   Server checks token in DB, issues new pair,
   deletes old refresh token entry, saves new one.
   <-- new access + new refresh

How it works step by step

1. User logs in with credentials. Server validates them, generates an access token (e.g., 15 min) and a refresh token (e.g., 7 days).
2. Server stores the refresh token (or its jti + expiry + user ID) in a database table or Redis keyed by user_id.
3. Client stores both tokens (ideally in HttpOnly cookies to prevent XSS theft — but local storage is common in SPAs).
4. On access token expiry (HTTP 401), the client calls /auth/refresh with the refresh token.
5. Server verifies the JWT signature, checks its jti exists in the store, and checks if it's not expired.
6. Rotation: server deletes the old token from the store, creates a new access + refresh pair, saves the new refresh token, and returns both.
7. If a client uses an already-used refresh token, the server detects it (token not found) and can revoke the entire family (all tokens for that user) — a security feature.
8. Logout deletes the refresh token from the store; the access token still works until it expires, which is acceptable.

Key design decisions:

• Storage: a database table refresh_tokens with columns id, jti, user_id, expires_at, created_at, revoked.
• Refresh token payload: include sub (user ID), exp (expiry), jti (unique ID). Do NOT include scopes or roles — those belong to access token.
• Token endpoint: use OAuth2 password flow for login, and a dedicated refresh flow.

Hands-on walkthrough

Let's build a minimal but complete implementation using FastAPI, PyJWT, and SQLAlchemy. We'll assume you have a User model already. First, install dependencies:

pip install fastapi uvicorn python-jose[cryptography] sqlalchemy

1. Database model for refresh tokens

from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey
from sqlalchemy.sql import func
from .database import Base

class RefreshToken(Base):
    __tablename__ = "refresh_tokens"

    id = Column(Integer, primary_key=True, index=True)
    jti = Column(String, unique=True, index=True)
    user_id = Column(Integer, ForeignKey("users.id"))
    expires_at = Column(DateTime)
    created_at = Column(DateTime, server_default=func.now())
    revoked = Column(Boolean, default=False)

2. Token creation and verification utilities

# security.py
from datetime import datetime, timedelta, timezone
from jose import jwt, JWTError

SECRET_KEY = "your-secret-key"  # use env var in production
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 15
REFRESH_TOKEN_EXPIRE_DAYS = 7

def create_access_token(user_id: int):
    payload = {
        "sub": str(user_id),
        "exp": datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES),
        "type": "access"
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

def create_refresh_token(user_id: int, jti: str):
    payload = {
        "sub": str(user_id),
        "exp": datetime.now(timezone.utc) + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS),
        "type": "refresh",
        "jti": jti
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

def decode_token(token: str) -> dict:
    try:
        return jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
    except JWTError:
        return None

3. Refresh endpoint with rotation

# main.py
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from sqlalchemy.orm import Session
from uuid import uuid4

app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login")

def get_current_user(token: str = Depends(oauth2_scheme)):
    payload = decode_token(token)
    if not payload or payload.get("type") != "access":
        raise HTTPException(status_code=401, detail="Invalid or expired access token")
    return int(payload["sub"])

@app.post("/auth/login")
def login(form: OAuth2PasswordRequestForm = Depends(), db: Session = Depends(get_db)):
    # verify credentials (simplified)
    user = db.query(User).filter(User.username == form.username).first()
    if not user or not verify_password(form.password, user.hashed_password):
        raise HTTPException(status_code=401, detail="Incorrect username or password")

    access = create_access_token(user.id)
    jti = str(uuid4())
    refresh = create_refresh_token(user.id, jti)

    db.add(RefreshToken(
        jti=jti, user_id=user.id,
        expires_at=datetime.now(timezone.utc) + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
    ))
    db.commit()

    return {"access_token": access, "refresh_token": refresh, "token_type": "bearer"}

@app.post("/auth/refresh")
def refresh(refresh_token: str = Depends(oauth2_scheme), db: Session = Depends(get_db)):
    payload = decode_token(refresh_token)
    if not payload or payload.get("type") != "refresh":
        raise HTTPException(status_code=401, detail="Invalid refresh token")

    token_record = db.query(RefreshToken).filter(
        RefreshToken.jti == payload["jti"]
    ).first()

    if not token_record or token_record.revoked:
        # Possible token reuse attack — revoke all tokens for this user
        db.query(RefreshToken).filter(RefreshToken.user_id == payload["sub"]).update({"revoked": True})
        db.commit()
        raise HTTPException(status_code=401, detail="Refresh token has been revoked")

    if token_record.expires_at < datetime.now(timezone.utc):
        db.delete(token_record)
        db.commit()
        raise HTTPException(status_code=401, detail="Refresh token expired")

    # Rotation: delete old, create new
    db.delete(token_record)
    new_jti = str(uuid4())
    new_refresh = create_refresh_token(payload["sub"], new_jti)
    db.add(RefreshToken(
        jti=new_jti, user_id=payload["sub"],
        expires_at=datetime.now(timezone.utc) + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
    ))
    db.commit()

    new_access = create_access_token(payload["sub"])
    return {"access_token": new_access, "refresh_token": new_refresh, "token_type": "bearer"}

@app.post("/auth/logout")
def logout(refresh_token: str = Depends(oauth2_scheme), db: Session = Depends(get_db)):
    payload = decode_token(refresh_token)
    if payload:
        db.query(RefreshToken).filter(RefreshToken.jti == payload.get("jti")).delete()
        db.commit()
    return {"message": "Logged out"}

Expected behavior:

POST /auth/login → {"access_token": "...", "refresh_token": "..."}
POST /auth/refresh (with old refresh) → new pair; old one deleted
POST /auth/refresh (with the same old refresh again) → 401 and all tokens revoked

Compare options / when to choose what

Recommendation: Start with rotation + HttpOnly cookies for web apps; for pure API clients, use rotation with Bearer tokens stored securely. Add token families if you need to revoke all sessions after password change.

Troubleshooting & edge cases

• Error: "Invalid refresh token" after rotation — You probably used the same refresh token twice. The old one was deleted; the client must store the new one after each refresh.
• Access token expires before client refreshes — Add an HTTP interceptor that calls /auth/refresh on 401 and retries the request. Don't refresh on every API call.
• User logs out but access token still works — Acceptable; access tokens are short-lived. To force expiry, keep a token_version in the DB and include it in the token claims; check it on each request.
• Clock skew between servers — Use leeway in jwt.decode (e.g., leeway=30) to avoid premature expiry.
• Database lookup fails because token isn't there — Make sure you store the refresh token at login, not just on refresh; else rotation breaks.
• Stale tokens in DB — Add a background job to delete expired tokens; otherwise the table grows unbounded.

What you learned & what's next

You learned why short access tokens are safer, how refresh tokens decouple session longevity from token lifetime, and how rotation makes stolen tokens useless after one use. You implemented a full flow: login, refresh with rotation, detection of token reuse, and logout. You also know when to choose rotation vs. other approaches.

Next lesson: Implementing role-based access control — where you'll extend your JWT payload with roles and enforce permissions on endpoints. You'll reuse the token infrastructure you built here.

Key takeaways for this lesson:

• Access tokens should be short-lived (minutes); refresh tokens long-lived (days) but protected by rotation.
• Always store refresh tokens server-side to enable revocation and reuse detection.
• On every refresh, delete the old token and issue a new pair — never keep the same refresh token twice.
• Detect token reuse by checking for missing/revoked records and revoke the whole family.
• Use HttpOnly cookies for web apps to reduce XSS risk.
• Plan for token cleanup with a scheduled job.