FastAPI Backend Development Bootcamp · Урок

Токены обновления и ротация токенов

Проектируйте короткоживущие токены доступа с меняющимися токенами обновления и отзывом на стороне сервера для снижения риска кражи токенов.

«Токены обновления и ротация токенов» — бесплатный урок FastAPI Backend Development Bootcamp на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения FastAPI Backend Development Bootcamp, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс FastAPI Backend Development Bootcamp содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Why Two Tokens?

A single long-lived JWT access token is convenient but dangerous: if it leaks, an attacker can use it until it expires. Since JWTs are stateless, you cannot easily revoke one mid-flight.

The standard OAuth2 answer is to split responsibilities into two tokens:

Access token — short-lived (5-15 min), sent on every request, verified by signature only (no DB hit).
Refresh token — long-lived (days/weeks), used only to obtain a new access token, and tracked server-side so it can be revoked.

This way a stolen access token is useless within minutes, while users still stay logged in for a long time.

Anatomy of the Token Pair

The login endpoint returns both tokens. The client keeps the access token in memory and the refresh token somewhere more protected (e.g. an HttpOnly cookie).

Notice the very different expiry windows. The access token is intentionally short so a leak has a tiny blast radius.

from datetime import datetime, timedelta, timezone

ACCESS_TOKEN_TTL = timedelta(minutes=15)
REFRESH_TOKEN_TTL = timedelta(days=7)

def expiry(ttl: timedelta) -> str:
    return (datetime.now(timezone.utc) + ttl).isoformat()

login_response = {
    "access_token": "<jwt>",
    "access_expires": expiry(ACCESS_TOKEN_TTL),
    "refresh_token": "<opaque-or-jwt>",
    "refresh_expires": expiry(REFRESH_TOKEN_TTL),
    "token_type": "bearer",
}

for k, v in login_response.items():
    print(f"{k}: {v}")

Signing an Access Token

Access tokens are JWTs signed with your secret. They carry a sub (user id), an exp claim, and a type claim so the server can refuse a refresh token where an access token is expected.

This snippet uses python-jose, the library most FastAPI tutorials rely on. It depends on an external package, so it is not standalone-runnable here.

from datetime import datetime, timedelta, timezone
from jose import jwt

SECRET = "change-me"
ALGO = "HS256"

def create_access_token(user_id: str) -> str:
    now = datetime.now(timezone.utc)
    payload = {
        "sub": user_id,
        "type": "access",
        "iat": now,
        "exp": now + timedelta(minutes=15),
    }
    return jwt.encode(payload, SECRET, algorithm=ALGO)

The Refresh Token Needs State

An access token is verified by signature alone — no database needed. A refresh token is different: to support revocation and rotation, the server must remember it.

The trick: never store the raw refresh token. Store only a hash of it, just like a password. If your DB leaks, the stored hashes cannot be replayed.

Generate a high-entropy random string as the token.
Hash it (SHA-256) and persist the hash, user id, expiry, and a revoked flag.
On refresh, hash the incoming token and look it up.

import hashlib, secrets

def new_refresh_token() -> tuple[str, str]:
    raw = secrets.token_urlsafe(48)          # give this to the client
    token_hash = hashlib.sha256(raw.encode()).hexdigest()  # store this
    return raw, token_hash

raw, stored = new_refresh_token()
print("client receives:", raw[:16], "...")
print("db stores hash :", stored[:16], "...")
print("lookup matches :", hashlib.sha256(raw.encode()).hexdigest() == stored)

What Is Token Rotation?

Rotation means every time a refresh token is used, it is consumed and replaced by a brand-new one. A refresh token is therefore single-use.

Sequence on each refresh:

Validate the presented refresh token (exists, not revoked, not expired).
Mark it revoked/used.
Issue a fresh access token and a fresh refresh token.
Return the new pair to the client.

Without rotation, a stolen refresh token works for its entire lifetime. With rotation, using it changes it — which is exactly what lets us detect theft.

Modeling the Stored Token

Here is a minimal in-memory model of the refresh-token store so you can see the moving parts before wiring a real database. Each record knows its owner, expiry, and whether it has been used or revoked.

In production this maps to a SQL table (with the hash as the key) or a Redis entry with a TTL.

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone

@dataclass
class RefreshRecord:
    token_hash: str
    user_id: str
    expires_at: datetime
    revoked: bool = False

    def is_valid(self, now: datetime) -> bool:
        return not self.revoked and now < self.expires_at

now = datetime.now(timezone.utc)
rec = RefreshRecord("abc123", "user-7", now + timedelta(days=7))
print("valid now      :", rec.is_valid(now))
rec.revoked = True
print("valid revoked  :", rec.is_valid(now))

The Rotation Logic

This is the heart of the lesson: a pure function that takes a presented refresh token, validates it, revokes it, and mints a replacement. No framework involved — just the algorithm.

Run it: the first refresh succeeds and returns a new token; reusing the old token afterward fails because it was rotated out.

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

store = {}  # token_hash -> {user_id, exp, revoked}

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

def issue(user_id):
    raw = secrets.token_urlsafe(32)
    store[_hash(raw)] = {
        "user_id": user_id,
        "exp": datetime.now(timezone.utc) + timedelta(days=7),
        "revoked": False,
    }
    return raw

def rotate(raw):
    rec = store.get(_hash(raw))
    now = datetime.now(timezone.utc)
    if not rec or rec["revoked"] or now >= rec["exp"]:
        raise ValueError("invalid refresh token")
    rec["revoked"] = True            # consume the old one
    return issue(rec["user_id"])     # mint a fresh one

old = issue("user-7")
new = rotate(old)
print("rotated to new token:", new[:12], "...")
try:
    rotate(old)
except ValueError as e:
    print("reuse of old token blocked:", e)

Detecting Token Theft via Reuse

Rotation gives a powerful security signal. If a refresh token that was already used shows up again, there are only two explanations:

The legitimate client never received the new token (rare), or
An attacker stole the old token and is replaying it.

Because you cannot tell which, the safe response is to treat reuse as a breach of the whole token family: revoke every refresh token for that user (or that session lineage) and force re-login.

This is called automatic reuse detection and is recommended by the OAuth2 Security Best Current Practice (RFC 9700).

Reuse Detection in Code

To detect reuse we keep a per-user family of tokens. A normal rotation revokes one token and adds its successor. If a token marked used=True is presented again, we nuke the entire family.

Run it to see a stolen-token replay trigger a full family wipe.

import secrets

family = {}  # token -> {"used": bool}

def issue():
    t = secrets.token_urlsafe(16)
    family[t] = {"used": False}
    return t

def rotate(t):
    rec = family.get(t)
    if rec is None:
        raise ValueError("unknown token")
    if rec["used"]:
        family.clear()  # reuse detected -> revoke whole family
        raise ValueError("REUSE DETECTED: all sessions revoked")
    rec["used"] = True
    return issue()

t1 = issue()
t2 = rotate(t1)      # normal rotation
print("rotation ok, new token issued")
try:
    rotate(t1)       # attacker replays the stolen old token
except ValueError as e:
    print(e)
print("tokens remaining:", len(family))

The FastAPI Refresh Endpoint

Now the FastAPI wiring. The refresh token arrives in the request body (or an HttpOnly cookie). The endpoint rotates it and returns a fresh pair.

Key choices visible here:

Reject anything that is not a refresh token type.
Return 401 on any validation failure — never leak why.
Always issue a new refresh token alongside the access token.

This depends on FastAPI and your store, so it is illustrative rather than standalone-runnable.

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel

router = APIRouter()

class RefreshIn(BaseModel):
    refresh_token: str

class TokenPair(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"

@router.post("/auth/refresh", response_model=TokenPair)
async def refresh(body: RefreshIn):
    try:
        user_id = validate_and_consume(body.refresh_token)  # raises on reuse/expiry
    except ValueError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid refresh token",
        )
    return TokenPair(
        access_token=create_access_token(user_id),
        refresh_token=create_refresh_token(user_id),
    )

Storing and Revoking Server-Side

Server-side state is what makes revocation possible. A logout, a password change, or a detected breach should immediately invalidate refresh tokens.

Practical guidance:

Where: SQL table for durability, or Redis with a TTL equal to the token lifetime for speed and automatic expiry.
What to store: the SHA-256 hash, user id, expiry, a revoked flag, and optionally a family_id for reuse detection.
Logout: mark the presented token (and optionally its whole family) revoked.
Global logout: revoke all of a user's tokens — e.g. after a password reset.

Access tokens stay stateless and simply expire on their own within minutes, which is why short TTLs matter so much.

def logout(token_hash: str, conn) -> None:
    conn.execute(
        "UPDATE refresh_tokens SET revoked = TRUE WHERE token_hash = %s",
        (token_hash,),
    )

def revoke_all_for_user(user_id: str, conn) -> None:
    conn.execute(
        "UPDATE refresh_tokens SET revoked = TRUE WHERE user_id = %s",
        (user_id,),
    )

Quick Check

Test your understanding of the core rotation decision.

Recap

You now know how to build secure session management with rotating refresh tokens:

Two tokens: short-lived stateless access tokens (5-15 min) plus long-lived refresh tokens tracked server-side.
Hash, never store raw: persist only the SHA-256 of the refresh token, like a password.
Rotation: every refresh consumes the old token (single-use) and issues a fresh pair.
Reuse detection: a replayed used token means likely theft — revoke the whole family and force re-login (RFC 9700).
Revocation: server-side state (SQL or Redis-with-TTL) lets logout, password change, and breach response invalidate tokens instantly.

The result: a stolen access token dies in minutes, a stolen refresh token is detected on first replay, and users still enjoy long-lived sessions.

Часто задаваемые вопросы

Урок «Токены обновления и ротация токенов» бесплатный?

Да — полный текст урока «Токены обновления и ротация токенов» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс FastAPI Backend Development Bootcamp, подпишись на CoddyKit PRO. Курс FastAPI Backend Development Bootcamp содержит 4 уроков всего.

Чему я научусь в уроке «Токены обновления и ротация токенов»?

Проектируйте короткоживущие токены доступа с меняющимися токенами обновления и отзывом на стороне сервера для снижения риска кражи токенов. Ты практикуешь FastAPI Backend Development Bootcamp с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать FastAPI Backend Development Bootcamp?

Предыдущий опыт не требуется. FastAPI Backend Development Bootcamp на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Токены обновления и ротация токенов»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке FastAPI Backend Development Bootcamp?

Да. Каждый урок FastAPI Backend Development Bootcamp включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Поток пароля OAuth2 и выдача токенов
Подписание и проверка JWT с помощью python-jose
Токены обновления и ротация токенов
Авторизация на основе областей и защиты ролей

← Назад к FastAPI Backend Development Bootcamp