Token Refresh and Revocation

The Necessity of Dual-Token Architecture

To build a secure system, you must accept that tokens will eventually be leaked. If you use a single long-lived access token, a compromised token grants an attacker indefinite access until the secret key is rotated. By introducing a dual-token system, we split the responsibility. The Access Token, typically valid for 15-30 minutes, is sent with every API request to authorize access to protected routes. Because it is short-lived, the impact of a leak is minimized. The Refresh Token is stored securely, perhaps in an HttpOnly cookie, and is used solely to request a new pair of tokens when the access token expires. This design effectively forces a recurring 'heartbeat' check against your database, allowing you to verify that the user account has not been disabled or had its password changed, ensuring security remains synchronized with your backend state.

from fastapi import FastAPI, Depends
from datetime import datetime, timedelta
import jwt

# Short-lived access token (15 mins)
# Long-lived refresh token (7 days)
SECRET = "super-secure-key"

def create_tokens(user_id: str):
    access = jwt.encode({"sub": user_id, "exp": datetime.utcnow() + timedelta(minutes=15)}, SECRET)
    refresh = jwt.encode({"sub": user_id, "exp": datetime.utcnow() + timedelta(days=7)}, SECRET)
    return {"access": access, "refresh": refresh}

Implementing the Token Refresh Flow

The refresh flow is essentially a specialized login endpoint. When the frontend detects an expired access token, it must not ask the user for their credentials again, as that provides a poor experience. Instead, it hits a dedicated /refresh endpoint, sending the valid Refresh Token. Your FastAPI application validates the refresh token’s signature and expiration. Crucially, you must then look up the user in your database to ensure their account is still active—for instance, checking if the user was deleted or if the session was explicitly revoked. If valid, you issue a fresh access token (and optionally a new refresh token, known as refresh token rotation). This flow prevents the need for persistent re-authentication while maintaining the ability to cut off access by invalidating tokens stored in your database or by checking a 'last login' timestamp against the token's 'issued at' claim.

from fastapi import HTTPException, Header

@app.post("/refresh")
def refresh_token(refresh_token: str = Header(...)):
    try:
        payload = jwt.decode(refresh_token, SECRET, algorithms=["HS256"])
        # Verify user is still allowed to access the system in the DB
        new_access = jwt.encode({"sub": payload["sub"], "exp": datetime.utcnow() + timedelta(minutes=15)}, SECRET)
        return {"access": new_access}
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Refresh token expired")

Strategies for Token Revocation

Revocation is the 'kill switch' for stateless tokens. Since JWTs are self-contained, they are natively valid until expiration; the server does not usually consult the database to authorize every request. To bypass this, we use a blocklist. When a user logs out or if an admin bans an account, you store the token's unique identifier (jti) in a fast, distributed key-value store like Redis, setting the expiration to match the remaining life of the token. In your dependency chain, you check the blocklist before processing the request. While this adds a small latency penalty, it is the only way to achieve granular session control. Alternatively, you can store a 'token_version' or 'issued_after' timestamp on the user model, rejecting any tokens issued before that timestamp, which effectively revokes all previously issued tokens for that specific user.

import redis

# Connect to Redis to track revoked tokens
revoked_tokens = redis.Redis(host='localhost', port=6379, db=0)

def is_revoked(jti: str):
    return revoked_tokens.exists(jti)

# Usage in dependency
def get_current_user(token: str):
    payload = jwt.decode(token, SECRET, algorithms=["HS256"])
    if is_revoked(payload.get("jti")):
        raise HTTPException(status_code=401, detail="Token has been revoked")
    return payload

Refresh Token Rotation for Enhanced Security

Refresh token rotation takes the security of the refresh flow to the next level by ensuring that every time a refresh token is used, it is consumed and replaced by a brand-new one. This is highly effective against token theft. If an attacker manages to steal a refresh token and uses it to obtain a new access token, the legitimate user will later attempt to use their own (now-stale) refresh token. Your server will detect that a 'used' token is being presented, which is a major red flag indicating a potential security breach. In response, you can immediately invalidate the entire refresh family for that user, forcing them to authenticate via credentials again. This creates a high-stakes environment for attackers, as any misuse or racing condition will likely result in the session being terminated, protecting the user's account.

# Concept: Mark old refresh token as used in DB
# If a token is presented that is marked as 'used', revoke all tokens for this user
def rotate_refresh_token(old_token_jti: str, user_id: str):
    if db.is_token_used(old_token_jti):
        db.revoke_all_sessions(user_id)
        raise HTTPException(status_code=403, detail="Replay attack detected")
    db.mark_as_used(old_token_jti)
    return create_tokens(user_id)

Handling Expiration and User Experience

Managing the expiration of tokens requires a thoughtful balance between security and user convenience. If access tokens are too short (e.g., 1 minute), your backend will be overwhelmed by constant refresh requests. If they are too long, the revocation window remains wide open for attackers. A practical strategy involves a silent background refresh: the frontend monitors the expiration claim of the JWT and triggers the /refresh endpoint automatically just before the token expires. If the refresh request itself fails—perhaps because the refresh token has also expired—the application must gracefully redirect the user to the login page. By implementing this 'silent refresh', the user stays authenticated as long as they are active, but remains subject to security policies, such as maximum session duration or account deactivation, without needing to manually re-login frequently.

from fastapi import Depends, HTTPException

def verify_access_token(token: str):
    try:
        return jwt.decode(token, SECRET, algorithms=["HS256"])
    except jwt.ExpiredSignatureError:
        # Trigger client to call /refresh
        raise HTTPException(status_code=401, headers={"WWW-Authenticate": "Bearer error=\"token_expired\""})
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401)

Interview questions

All FastAPI interview questions →

Check yourself

Take the full FastAPI quiz →