JWT Authentication and Role-Based Access in FastAPI

Most real APIs need to know who is making a request and whether they’re allowed to do what they’re asking. This lesson implements a complete, production-ready authentication system using JSON Web Tokens (JWT) — the recommended approach for stateless REST APIs. You’ll build user registration and login endpoints, token generation with expiry, a get_current_user dependency that protects routes, and role-based access control (RBAC) that restricts specific endpoints to admin users. Every piece follows the pattern used in production FastAPI applications.

Authentication Models Compared

JWT (Recommended for APIs)
Session-Based
HTTP Basic

The server issues a signed token at login. The client stores it and sends it with every subsequent request. The server verifies the signature — no database lookup needed per request.Best for: REST APIs, SPAs, mobile apps, microservices. Advantage: Stateless, scales horizontally with no shared session storage.

Credentials (username + password) are sent with every request in the Authorization header, Base64-encoded.Best for: Simple internal tool or development setups only. Drawback: High risk if any request is intercepted; redundant database lookups.

What is a JWT?

A JSON Web Token is a compact, URL-safe string containing signed claims (statements about a user) that the server can verify without querying a database. A JWT has three dot-separated parts:

Header.Payload.Signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJyb2xlIjoiYWRtaW4ifQ.signature

Header — algorithm (HS256) and token type (JWT), Base64URL-encoded.
Payload — claims: sub (subject/user ID), exp (expiry), role, and any other data you include.
Signature — HMAC(base64(header) + "." + base64(payload), SECRET_KEY). Any change to the header or payload invalidates the signature.

The payload is only Base64URL-encoded, not encrypted. Anyone who has the token can decode and read the payload. Never store passwords, credit card numbers, or other sensitive data inside a JWT payload.

JWT Authentication Lifecycle

CLIENT                                                   SERVER
  │                                                        │
  ├────── 1. POST /login (username + password) ──────────>┤
  │                                                        │ — Verify credentials
  │                                                        │ — Sign JWT with SECRET_KEY
  │<───── 2. Return { access_token, token_type } ─────────┤
  │                                                        │
  │   ── Subsequent Requests ──                            │
  │                                                        │
  ├────── 3. GET /profile                                 >┤
  │          Authorization: Bearer <access_token>          │ — Decode & verify signature
  │                                                        │ — Check expiry (exp)
  │                                                        │ — Retrieve user identity (sub)
  │<───── 4. 200 OK with user data  (or 401) ─────────────┤

Step-by-Step Implementation

Step 1: Install Dependencies

pip install fastapi uvicorn sqlmodel pyjwt "passlib[bcrypt]" python-multipart

Package	Purpose
`pyjwt`	JWT encoding and decoding
`passlib[bcrypt]`	Secure password hashing
`python-multipart`	Allows form-based credential submission

Step 2: User Model

# models.py
from typing import Optional
from sqlmodel import SQLModel, Field

class User(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    username: str = Field(index=True, unique=True, nullable=False)
    password: str = Field(nullable=False)   # stores the bcrypt hash
    role: str = Field(default="user")       # "user" or "admin"

class RegisterRequest(SQLModel):
    username: str
    password: str

class LoginRequest(SQLModel):
    username: str
    password: str

Step 3: Password Hashing

Never store plain-text passwords. Use bcrypt to hash on registration and verify at login:

# security.py
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(password: str) -> str:
    return pwd_context.hash(password)

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

Step 4: Token Generation

# jwt_handler.py
from datetime import datetime, timedelta, timezone
import jwt

SECRET_KEY = "your-extremely-secure-random-secret-key"  # use an env variable in production
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

def create_access_token(data: dict) -> str:
    payload = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    payload.update({"exp": expire})
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

In production, load SECRET_KEY from an environment variable using os.getenv("SECRET_KEY") or a Pydantic BaseSettings class. Never commit secrets to version control.

# routers/auth.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlmodel import Session, select
from database import get_session
from models import User, RegisterRequest, LoginRequest
from security import hash_password, verify_password
from jwt_handler import create_access_token

router = APIRouter(prefix="/auth", tags=["Authentication"])


@router.post("/register", status_code=status.HTTP_201_CREATED)
def register(request: RegisterRequest, session: Session = Depends(get_session)):
    # Prevent duplicate usernames
    existing = session.exec(select(User).where(User.username == request.username)).first()
    if existing:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Username already exists."
        )

    new_user = User(
        username=request.username,
        password=hash_password(request.password),
        role="user"
    )
    session.add(new_user)
    session.commit()
    return {"message": "User registered successfully."}


@router.post("/login")
def login(request: LoginRequest, session: Session = Depends(get_session)):
    user = session.exec(select(User).where(User.username == request.username)).first()

    if not user or not verify_password(request.password, user.password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid username or password."
        )

    access_token = create_access_token(
        data={
            "sub": str(user.id),
            "username": user.username,
            "role": user.role
        }
    )
    return {"access_token": access_token, "token_type": "bearer"}

Step 6: Bearer Token Verification Dependency

This dependency extracts the JWT from the Authorization: Bearer <token> header, verifies its signature and expiry, and returns the authenticated user:

# dependencies.py
import jwt
from typing import Annotated
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from sqlmodel import Session
from database import get_session
from models import User
from jwt_handler import SECRET_KEY, ALGORITHM

bearer_scheme = HTTPBearer()

def get_current_user(
    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
    session: Session = Depends(get_session)
) -> User:
    token = credentials.credentials
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        user_id: str | None = payload.get("sub")
        if user_id is None:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="Token payload is missing user identification."
            )
    except jwt.ExpiredSignatureError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Token has expired. Please log in again."
        )
    except jwt.PyJWTError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid authentication token."
        )

    user = session.get(User, int(user_id))
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Authenticated user no longer exists."
        )
    return user

# Reusable typed alias
CurrentUserDep = Annotated[User, Depends(get_current_user)]

Step 7: Protecting Routes

Apply get_current_user to any endpoint that requires authentication:

# routers/users.py
from fastapi import APIRouter
from dependencies import CurrentUserDep

router = APIRouter(tags=["Users"])

# Any authenticated user can access this
@router.get("/profile")
def get_profile(current_user: CurrentUserDep):
    return {
        "id": current_user.id,
        "username": current_user.username,
        "role": current_user.role
    }

Step 8: Role-Based Access Control (RBAC)

Use a dependency factory to restrict endpoints to specific roles:

# dependencies.py (continued)
from fastapi import Depends, HTTPException, status
from models import User

def require_roles(*allowed_roles: str):
    """
    Returns a dependency that checks whether the current user has one of the allowed roles.
    """
    def authorize(user: User = Depends(get_current_user)) -> User:
        if user.role not in allowed_roles:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Access denied. Insufficient role permissions."
            )
        return user
    return authorize

Apply role requirements directly in the route decorator:

from fastapi import APIRouter, Depends
from dependencies import get_current_user, require_roles
from models import User

router = APIRouter(tags=["Protected"])

# Requires any authenticated user
@router.get("/dashboard")
def dashboard(current_user: User = Depends(get_current_user)):
    return {"message": f"Welcome, {current_user.username}!"}

# Requires the 'admin' role
@router.get("/admin/logs")
def view_logs(admin: User = Depends(require_roles("admin"))):
    return {"message": "Admin access granted — here are the system logs."}

# Requires either 'author' or 'admin' role
@router.post("/articles")
def publish_article(creator: User = Depends(require_roles("author", "admin"))):
    return {"message": f"Article published by {creator.username}."}

Testing in Swagger UI

Open Swagger UI

Navigate to http://127.0.0.1:8000/docs.

Use POST /auth/register to create a test user.

Use POST /auth/login with your credentials. Copy the access_token value from the JSON response.

Authorise in Swagger

Click the green Authorize 🔒 button at the top of the page. Paste your token in the value field and click Authorize.

Call protected endpoints

Now call /profile or any protected route — Swagger will automatically include the Authorization: Bearer <token> header.

Summary

Step	What you built
Password hashing	`hash_password()` and `verify_password()` with bcrypt
Token creation	`create_access_token()` with `sub`, `role`, and `exp` claims
Login endpoint	`POST /auth/login` returns `{ access_token, token_type }`
Token verification	`get_current_user` dependency decodes and validates the Bearer token
Route protection	`Depends(get_current_user)` on any endpoint that requires authentication
Role enforcement	`require_roles("admin")` dependency factory for fine-grained access control

SQL & Databases

Data Analysis

FastAPI

Frontend

JWT Authentication and Role-Based Access in FastAPI

Authentication Models Compared

What is a JWT?

JWT Authentication Lifecycle

Step-by-Step Implementation

Step 1: Install Dependencies

Step 2: User Model

Step 3: Password Hashing

Step 4: Token Generation

Step 6: Bearer Token Verification Dependency

Step 7: Protecting Routes

Step 8: Role-Based Access Control (RBAC)

Testing in Swagger UI

Summary

​Authentication Models Compared

​What is a JWT?

​JWT Authentication Lifecycle

​Step-by-Step Implementation

​Step 1: Install Dependencies

​Step 2: User Model

​Step 3: Password Hashing

​Step 4: Token Generation

​Step 5: Registration and Login Endpoints

​Step 6: Bearer Token Verification Dependency

​Step 7: Protecting Routes

​Step 8: Role-Based Access Control (RBAC)

​Testing in Swagger UI

​Summary

Authentication Models Compared

What is a JWT?

JWT Authentication Lifecycle

Step-by-Step Implementation

Step 1: Install Dependencies

Step 2: User Model

Step 3: Password Hashing

Step 4: Token Generation

Step 5: Registration and Login Endpoints

Step 6: Bearer Token Verification Dependency

Step 7: Protecting Routes

Step 8: Role-Based Access Control (RBAC)

Testing in Swagger UI

Summary