Refresh Token Rotation and Reuse Detection with FastAPI

Key facts, with sources

• Compromised credentials are the initial-access vector in 22% of breaches, and credential stuffing makes up a median 19% of login attempts. (Verizon 2025 DBIR)

Why rotation alone is not enough

Rotation on its own just moves the target. If every refresh mints a new token but you never notice the old one being replayed, an attacker who copied a refresh token can keep refreshing in parallel with the real user and stay logged in indefinitely. What actually protects the session is detection: the moment a token you already retired shows up again, you know either the client or the attacker is holding a stale copy — and you cannot tell which, so you revoke everything and make both re-authenticate.

The mechanism is a token family. Every login starts a family; every rotation adds a link to the chain but keeps the same family_id. Retired links are marked revoked, not deleted. Presenting a revoked link is the signal that something forked the chain.

Model refresh tokens as a hashed family

Store one row per issued refresh token. Never store the raw token — hash it, so a database leak does not hand out live sessions. Group rows by family_id so reuse detection can revoke the whole chain in a single query.

class RefreshToken(Base):
    __tablename__ = "refresh_tokens"
    id = Column(String, primary_key=True)      # the jti of this link
    family_id = Column(String, index=True)     # shared across a rotation chain
    user_id = Column(String, index=True)
    token_hash = Column(String, index=True)    # sha256 of the raw token
    revoked = Column(Boolean, default=False)
    expires_at = Column(DateTime)

The rotate-and-detect endpoint

The refresh endpoint does four things in order: look the token up by hash, reject unknown or expired tokens, detect reuse of a retired token, and only then rotate. The reuse branch is the whole point — it revokes the family before issuing anything.

import hashlib, secrets
from datetime import datetime, timedelta, timezone

def _hash(raw: str) -> str:
    return hashlib.sha256(raw.encode()).hexdigest()

@router.post("/auth/refresh")
def refresh(body: RefreshIn, db: Session = Depends(get_db)):
    row = db.query(RefreshToken).filter_by(token_hash=_hash(body.refresh_token)).first()

    # Unknown or expired -> reject outright.
    if row is None or row.expires_at < datetime.now(timezone.utc):
        raise HTTPException(401, "invalid refresh token")

    # Reuse detection: a revoked link was already rotated once. Its reappearance
    # means the chain forked -> burn the whole family, force a fresh login.
    if row.revoked:
        db.query(RefreshToken).filter_by(family_id=row.family_id).update({"revoked": True})
        db.commit()
        raise HTTPException(401, "token reuse detected - session revoked")

    # Rotate: retire the presented link, mint a new one in the same family.
    row.revoked = True
    new_raw = secrets.token_urlsafe(32)
    db.add(RefreshToken(
        id=secrets.token_hex(16),
        family_id=row.family_id,
        user_id=row.user_id,
        token_hash=_hash(new_raw),
        expires_at=datetime.now(timezone.utc) + timedelta(days=14),
    ))
    db.commit()
    return {"access_token": mint_access_token(row.user_id), "refresh_token": new_raw}

Why this makes the mobile refresh race non-optional

On the client, the deduplicated single-flight refresh from the React Native JWT guide stops being a nice-to-have and becomes mandatory. Without rotation, two parallel 401s each firing their own refresh is merely wasteful. With rotation, the first refresh retires the token and the second arrives holding a value you just revoked — which trips reuse detection and logs the user out for no reason.

So the two halves are a matched pair: the server rotates and detects reuse, and the client must funnel every concurrent 401 through one shared refresh promise so exactly one rotation happens per cycle. Ship one without the other and you get either an insecure session or a client that logs itself out at random.

Logout and cleanup

Logout revokes the current family so the refresh token cannot be reused after sign-out. Give each device its own family at login, so signing out on a phone does not kill the tablet. Run a periodic job to delete rows past expires_at — reuse detection only needs live and recently-retired links, not months of history.

When to hire senior help

Bring in senior help when your API needs to handle real concurrency, when you are designing service boundaries and auth for the first time, or when an existing FastAPI codebase mixes sync and async code and latency is degrading. An experienced engineer can usually diagnose event-loop blocking and connection-pool misconfiguration in days, which is far cheaper than re-architecting after launch. If your stack includes React Native + Python + AI, a senior engineer who owns the full product beats coordinating multiple juniors.

Bottom line

Dhairya Senjaliya ships Python — FastAPI Development projects worldwide — book a scoping call to discuss your specific situation.

Common pitfalls to avoid

• ✕Calling blocking libraries (classic SQLAlchemy sessions, requests, heavy file I/O) inside async def endpoints, which stalls the event loop and erases FastAPI's concurrency advantage
• ✕Deploying a single Uvicorn process with no process manager or worker scaling, leaving most CPU cores idle under production load
• ✕Treating the auto-generated OpenAPI docs as a versioning strategy, then breaking mobile and partner clients when response schemas change
• ✕Running large payloads through deeply nested Pydantic models on every request and response, adding serialization latency that shows up only at scale

Frequently asked questions

Sources

• JetBrains Python Developers Survey 2024
• Stack Overflow Developer Survey 2025
• FastAPI official documentation
• DZone
• byteiota