🔐 libre-fastapi-jwt

Production-ready JWT authentication for FastAPI — access/refresh tokens, cookie storage with CSRF protection, JWKS, WebSocket auth, and token revocation, all in one dependency.

Documentation: https://LibreNZ.github.io/libre-fastapi-jwt Source Code: https://github.com/LibreNZ/libre-fastapi-jwt

Actively maintained by Libre NZ. Originally forked from fastapi-jwt-auth, now extensively rewritten and kept current.

Features

Requirements

Python 3.12, 3.13, or 3.14.

Installation

pip install libre-fastapi-jwt

For asymmetric (RSA/EC) key signing:

pip install 'libre-fastapi-jwt[asymmetric]'

Dependencies

All five packages are well-established, actively maintained, and widely used in the Python ecosystem. cryptography is the only one with compiled C extensions; the rest are pure Python.

Auth flow

sequenceDiagram
    participant C as Client
    participant A as FastAPI App

    C->>+A: POST /login (username + password)
    A-->>-C: { access_token, refresh_token }

    C->>+A: GET /protected (Authorization: Bearer <access_token>)
    A-->>-C: 200 OK — protected data

    Note over C,A: Access token expires (default 15 min)

    C->>+A: POST /refresh (Authorization: Bearer <refresh_token>)
    A-->>-C: { access_token }  ← new token, no re-login needed

Quick start

Header-based auth

from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel
from libre_fastapi_jwt import AuthJWT
from libre_fastapi_jwt.exceptions import AuthJWTException
from fastapi.responses import JSONResponse

app = FastAPI()

class Settings(BaseModel):
    authjwt_secret_key: str = "change-me-in-production"

@AuthJWT.load_config
def get_config():
    return Settings()

@app.exception_handler(AuthJWTException)
def authjwt_exception_handler(request, exc):
    return JSONResponse(status_code=exc.status_code, content={"detail": exc.message})

class LoginBody(BaseModel):
    username: str
    password: str

@app.post("/login")
def login(body: LoginBody, auth: AuthJWT = Depends()):
    if body.username != "alice" or body.password != "secret":
        raise HTTPException(status_code=401, detail="Bad credentials")
    return {
        "access_token": auth.create_access_token(subject=body.username),
        "refresh_token": auth.create_refresh_token(subject=body.username),
    }

@app.get("/protected")
def protected(auth: AuthJWT = Depends()):
    auth.jwt_required()
    return {"user": auth.get_jwt_subject()}

Refresh token flow

@app.post("/refresh")
def refresh(auth: AuthJWT = Depends()):
    auth.jwt_refresh_token_required()
    new_token = auth.create_access_token(subject=auth.get_jwt_subject())
    return {"access_token": new_token}

Cookie auth with CSRF protection

Cookies are the recommended approach for browser-based apps. __Host- prefixed cookie names and CSRF protection are enabled by default.

from fastapi import Response

class CookieSettings(BaseModel):
    authjwt_secret_key: str = "change-me-in-production"
    authjwt_token_location: list = ["cookies"]
    authjwt_cookie_secure: bool = True       # HTTPS only
    authjwt_cookie_csrf_protect: bool = True  # on by default

@AuthJWT.load_config
def get_config():
    return CookieSettings()

@app.post("/login")
def login(body: LoginBody, response: Response, auth: AuthJWT = Depends()):
    if body.username != "alice" or body.password != "secret":
        raise HTTPException(status_code=401, detail="Bad credentials")
    # Sets HttpOnly access + refresh cookies and CSRF cookies in one call
    auth.set_pair_cookies(
        auth.create_access_token(subject=body.username),
        auth.create_refresh_token(subject=body.username),
        response,
    )
    return {"detail": "Logged in"}

@app.delete("/logout")
def logout(response: Response, auth: AuthJWT = Depends()):
    auth.jwt_required()
    auth.unset_jwt_cookies(response)
    return {"detail": "Logged out"}

@app.get("/me")
def me(auth: AuthJWT = Depends()):
    auth.jwt_required()
    return {"user": auth.get_jwt_subject()}

Custom claims

@app.post("/login")
def login(body: LoginBody, auth: AuthJWT = Depends()):
    ...
    token = auth.create_access_token(
        subject=body.username,
        user_claims={"role": "admin", "org": "acme"},
    )
    return {"access_token": token}

@app.get("/admin")
def admin_only(auth: AuthJWT = Depends()):
    auth.jwt_required()
    claims = auth.get_raw_jwt()
    if claims.get("role") != "admin":
        raise HTTPException(status_code=403, detail="Admins only")
    return {"ok": True}

Configuration reference

Full configuration options: https://LibreNZ.github.io/libre-fastapi-jwt

Async-native verification

jwt_required, jwt_optional, jwt_refresh_token_required, and fresh_jwt_required are all async methods. This matters for denylist/revocation checks — the only place in a JWT library where real I/O (Redis, database) can occur. Token creation and cookie management remain synchronous since they involve no I/O.

You must await these calls from your route handlers:

@app.get("/protected")
async def protected(Authorize: AuthJWT = Depends()):
    await Authorize.jwt_required()
    return {"hello": Authorize.get_jwt_subject()}

The denylist callback transparently supports both sync and async implementations:

# Sync callback (e.g. in-memory set)
@AuthJWT.token_in_denylist_loader
def check_denylist(decoded_token: dict) -> bool:
    return decoded_token["jti"] in revoked_jtis

# Async callback (e.g. Redis)
@AuthJWT.token_in_denylist_loader
async def check_denylist(decoded_token: dict) -> bool:
    return await redis.sismember("revoked_jtis", decoded_token["jti"])

Both forms work without any code changes on the caller side.

Security defaults

Out of the box, libre-fastapi-jwt applies secure defaults so you don't have to think about them:

• __Host- cookie prefix — prevents cookie injection across subdomains and enforces Secure + root path
• HttpOnly cookies — tokens are never accessible to JavaScript
• CSRF double-submit — on by default for cookie mode; protects POST, PUT, PATCH, DELETE
• SameSite=Lax — sensible default; upgrade to strict for extra protection
• Weak algorithm rejection — the library enforces algorithm hygiene to prevent alg: none attacks

Examples

The examples/ directory covers:

• asymmetric.py — RSA/EC key signing
• denylist_redis.py — token revocation with Redis
• websocket.py — WebSocket authentication
• freshness.py — fresh token requirements for sensitive actions
• dual_token_location.py — headers + cookies simultaneously
• multiple_files/ — multi-file project structure

Test coverage

The test suite doubles as a functional specification. Each file below is a self-contained runnable guide for a specific area of the library.

tests/test_config.py — Configuration

• Default values for all config options
• Non-expiring tokens (False for expires)
• Missing secret key raises RuntimeError
• Denylist enabled without a callback raises an error
• Full round-trip loading of all options from an external settings source

tests/test_create_token.py — Token creation

• Parameter validation for access, refresh, and pair token creation
• Dynamic expiry overrides per token
• Audience, algorithm, and user_claims type checking
• Custom claims are correctly embedded in the payload

tests/test_decode_token.py — Token decoding & claims

• Expiry, leeway, and decode error handling
• Extracting raw token, JTI, and subject from requests
• Issuer and audience validation (valid and invalid cases)
• Algorithm mismatch detection
• RS256 asymmetric signing — valid and invalid key scenarios

tests/test_headers.py — Header-based auth

• Missing JWT, missing Bearer prefix, malformed token
• Valid Authorization: Bearer <token> flow
• Custom claims embedded in JWT headers
• Extracting JWT headers from request context
• Custom header name and custom header type configuration

tests/test_cookies.py — Cookie-based auth & CSRF

• Warning when cookies not in token location
• CSRF cookies set/not-set based on configuration
• Unsetting all cookies (access, refresh, CSRF)
• Custom cookie key names
• jwt_optional with CSRF variants
• Full CSRF double-submit validation across multiple URL patterns

tests/test_token_types.py — Token type claims

• Custom token type claim names
• Custom access/refresh type values
• Tokens operating without type claims entirely

tests/test_token_multiple_locations.py — Dual token locations

• Subject retrieval from either headers or cookies
• Refresh via cookie
• Token setting and unsetting across both locations

tests/test_denylist.py — Token revocation

• Non-denylisted access and refresh tokens pass through
• Denylisted access and refresh tokens are rejected

tests/test_websocket.py — WebSocket authentication

• Missing token, wrong token type, valid access token
• Optional JWT over WebSocket
• Refresh-only and fresh-token-only endpoints
• Invalid WebSocket instance type
• Missing cookie, missing CSRF token, missing CSRF claim
• CSRF double-submit mismatch and valid CSRF over WebSocket

tests/test_url_protected.py — Protected endpoint enforcement

• Missing header → 401
• Refresh token rejected on access-only endpoint
• jwt_required, jwt_optional, jwt_refresh_token_required, fresh_jwt_required

tests/test_kid.py — Key ID (kid) & JWKS

• kid placed in JOSE header (not body) for symmetric keys
• kid is the public key thumbprint for asymmetric keys
• Mismatched kid is rejected when validation is enabled
• Matching kid is accepted
• kid validation is opt-in (disabled by default)

License

MIT — see LICENSE.

Built and maintained by Libre NZ  ·  PyPI  ·  Docs  ·  GitHub