JWT Authentication in FastAPI — Secure APIs Properly

Introduction

Authentication is the part developers most often get wrong. This tutorial builds JWT auth in FastAPI the way a security review would actually approve: hashed passwords, short-lived access tokens, refresh tokens, and clean role-based access control.

For the Java version, see Spring Boot Security with JWT.

Key takeaways

• Hash passwords with bcrypt or argon2. Never with SHA-256.
• Access tokens should be short-lived (5–15 min). Use refresh tokens for the rest.
• Sign with HS256 for monoliths, RS256 for multi-service / public verification.
• RBAC belongs in a dependency, not scattered in handlers.
• Always validate exp, iss and aud claims.

Setup

pip install "passlib[bcrypt]" "python-jose[cryptography]" "pydantic[email]"

Password hashing

```python
from passlib.context import CryptContext
pwd = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(p: str) -> str: return pwd.hash(p) def verify_password(p: str, h: str) -> bool: return pwd.verify(p, h) ```

Token issuance

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

SECRET, ALG, ISS = settings.JWT_SECRET, "HS256", "masterlab"

def create_token(sub: str, roles: list[str], minutes: int) -> str: now = datetime.now(timezone.utc) return jwt.encode( {"sub": sub, "roles": roles, "iss": ISS, "iat": now, "exp": now + timedelta(minutes=minutes)}, SECRET, algorithm=ALG, ) ```

Login + refresh

```python
from fastapi import APIRouter, Depends, HTTPException
from fastapi.security import OAuth2PasswordRequestForm

router = APIRouter()

@router.post("/login") async def login(form: OAuth2PasswordRequestForm = Depends(), svc: UserService = Depends(get_user_service)): user = await svc.authenticate(form.username, form.password) if not user: raise HTTPException(401, "Invalid credentials") return { "access_token": create_token(str(user.id), user.roles, 15), "refresh_token": create_token(str(user.id), user.roles, 60 * 24 * 7), "token_type": "bearer", } ```

Current-user dependency

```python
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError

oauth2 = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")

async def current_user(token: str = Depends(oauth2)) -> dict: try: payload = jwt.decode(token, SECRET, algorithms=[ALG], issuer=ISS) except JWTError: raise HTTPException(401, "Invalid token") return payload

def require_roles(*roles: str): async def checker(user: dict = Depends(current_user)) -> dict: if not set(roles).intersection(user.get("roles", [])): raise HTTPException(403, "Insufficient role") return user return checker ```

Protecting endpoints

```python
@router.get("/me")
async def me(user: dict = Depends(current_user)):
    return {"id": user["sub"], "roles": user["roles"]}

@router.delete("/admin/users/{id}", dependencies=[Depends(require_roles("admin"))]) async def delete_user(id: int): ... ```

Production best practices

• Store refresh tokens in httpOnly, Secure, SameSite=Strict cookies — not localStorage.
• Maintain a token revocation list in Redis for logout / compromised tokens.
• Rotate JWT secrets; support kid in the header for graceful rotation.
• Rate-limit /login aggressively to slow credential stuffing.

Common mistakes

• Long-lived access tokens (days) — there is no logout if you can't revoke them.
• Signing tokens with the framework's default secret (changeme).
• Sending the JWT in URL query strings — it lands in logs.

Tools used in this tutorial

The setup below uses the following tools. Versions matter less than the role each one plays, so swap freely as long as you keep the responsibilities the same.

• Python 3.12+
• FastAPI
• Uvicorn / Gunicorn
• Pydantic v2
• SQLAlchemy 2.x
• Docker
• Kubernetes

Real-world production context

In production, a Python backend like this rarely runs as a single uvicorn process on a laptop. Teams build the app into a container image, push it to a registry, and run it behind a managed load balancer with autoscaling, health checks and centralized logging. Async FastAPI services typically use multiple Uvicorn workers managed by Gunicorn, a managed Postgres for state, Redis for cache and rate-limit counters, and an object store for uploads. The reason cloud hosting becomes a hard requirement is operational: zero-downtime rollouts, log aggregation, metrics, and TLS at the edge are not optional once real users depend on the API.

Recommended tools & deployment options

Once the tutorial works on your machine, the next question is *where do I run this for real?* These are the platforms most Python backend teams reach for:

• DigitalOcean — the simplest path from a working FastAPI container to a public URL. App Platform deploys directly from a Dockerfile, managed Postgres and Redis are one click away, and pricing is predictable. A common way to deploy the setup in this tutorial is using a cloud provider like DigitalOcean when you want to ship quickly without learning a full cloud SDK.
• AWS — the default for enterprise workloads. ECS Fargate or EKS run containers without you managing servers, RDS handles Postgres, and CloudWatch covers logs and metrics.
• Docker — the packaging format every modern deploy target understands. Build once, run the same image locally, in CI and in production.
• Kubernetes (managed: EKS, DOKS, GKE) — the right choice once you have more than a handful of services, need rolling updates, autoscaling and policy-driven networking.

A VPS or managed cloud service is required to run this architecture end-to-end — uvicorn --reload is for development, not for serving traffic.

FAQ

Sessions vs JWT? Server-side sessions with Redis are simpler and revocable. Prefer JWT when you have multiple services that need stateless verification.

Next steps & related tutorials

Keep the momentum going with the next tutorial in this learning path:

• Next: Building REST APIs with FastAPI
• Next: FastAPI Microservices Architecture
• Next: FastAPI Testing Strategy