FastAPI Security Production FAQ & Answers

Header() is a generic dependency injection tool for extracting ANY HTTP header value. Syntax: from fastapi import Header; async def get_token(authorization: str = Header()) extracts raw header string. Returns entire value including 'Bearer ' prefix. No automatic validation, no OpenAPI security schema, just string extraction. Requires manual parsing: token = authorization.split('Bearer ')[1]. Use for: custom headers (X-API-Key, X-Request-ID), non-standard authentication. HTTPBearer() is a specialized security scheme for OAuth 2.0 bearer token authentication per RFC 6750. Syntax: from fastapi.security import HTTPBearer; security = HTTPBearer(); async def get_token(credentials: HTTPAuthorizationCredentials = Depends(security)) automatically parses 'Authorization: Bearer ' header, returns HTTPAuthorizationCredentials object with .scheme ('Bearer') and .credentials (token string without prefix). Validates header format, raises 403 Forbidden if missing/malformed. Automatically adds security schema to OpenAPI docs (Swagger UI shows 'Authorize' button). Parameter auto_error=False returns None instead of raising exception if header missing (useful for optional auth). Comparison: Header() extracts raw string 'Bearer abc123', HTTPBearer() extracts parsed 'abc123' with validation. HTTPBearer() better for: OAuth access tokens, JWT authentication, standard bearer tokens. Header() better for: API keys in custom headers, non-Bearer authentication schemes, debugging. Production pattern: Use HTTPBearer for OAuth/JWT: security = HTTPBearer(); async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)): token = credentials.credentials; # Validate token. Use Header for API keys: async def verify_api_key(x_api_key: str = Header()): # Validate key. Best practice: HTTPBearer() provides automatic validation, better security, OpenAPI integration. Essential for OAuth 2.0/JWT APIs.

auto_error=False changes HTTPBearer behavior from raising HTTP 403 Forbidden exception when Authorization header is missing/invalid to returning None instead. Default behavior (auto_error=True): If 'Authorization: Bearer ' header missing or malformed, HTTPBearer raises HTTPException(status_code=403, detail='Not authenticated') immediately, request never reaches route handler. With auto_error=False: Missing/invalid header returns None for credentials parameter, route handler executes, allowing optional authentication logic. Use cases: (1) Optional authentication: Some endpoints allow both authenticated and anonymous access with different permissions. Example: Public API where authenticated users get higher rate limits. (2) Multiple authentication methods: Try OAuth token first, fall back to API key or session cookie. (3) Gradual authentication: Provide limited functionality without auth, full features with auth. Implementation pattern: from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials; security = HTTPBearer(auto_error=False); @app.get('/items') async def get_items(credentials: HTTPAuthorizationCredentials | None = Depends(security)): if credentials: user = await validate_token(credentials.credentials); return get_user_items(user); else: return get_public_items(). Security considerations: With auto_error=False, YOU must handle None case explicitly or risk unauthorized access. Never assume credentials is not None. Always check: if not credentials: # Handle anonymous user. Error handling: Raise custom exceptions with appropriate status codes. Return 401 for invalid tokens: if invalid_token: raise HTTPException(status_code=401, detail='Invalid token'). Return 403 for insufficient permissions: if not user.is_admin: raise HTTPException(status_code=403, detail='Forbidden'). Best practice: Use auto_error=True (default) for protected endpoints requiring authentication. Use auto_error=False only for optional auth scenarios with explicit None handling. Example optional auth: security = HTTPBearer(auto_error=False); async def optional_user(creds: HTTPAuthorizationCredentials | None = Depends(security)) -> User | None: return await validate_token(creds.credentials) if creds else None. Essential for flexible authentication patterns.

request.state mutations made in middleware BEFORE await call_next(request) are guaranteed to be visible to all downstream middleware and route handlers in the same request cycle. FastAPI uses Starlette's middleware system which processes middleware sequentially in a stack pattern. Execution flow: (1) Middleware A sets request.state.user = user before call_next(). (2) Middleware A calls response = await call_next(request). (3) Middleware B (downstream) sees request.state.user before its call_next(). (4) Route handler sees request.state.user. (5) Middleware B executes code after call_next() (response processing). (6) Middleware A executes code after call_next() (outer cleanup). Pattern: Middleware wraps like onion layers: A_before → B_before → handler → B_after → A_after. State access example: @app.middleware('http'); async def auth_middleware(request: Request, call_next): request.state.user_id = extract_user_id(request); response = await call_next(request); return response. Route uses state: @app.get('/profile'); async def profile(request: Request): user_id = request.state.user_id; return get_profile(user_id). Thread safety: request.state is request-scoped, isolated per request in async context. Each request gets unique Request object with separate state. Not shared across requests. No race conditions. Mutation after call_next(): Changes to request.state AFTER call_next() are visible only in remaining middleware stack (outer layers), NOT to inner layers or route handlers (already executed). Persistence: request.state cleared when request completes. Not persisted across requests. Use for: Per-request context (current user, request ID, timing data, database connections). Best practice: Set state in middleware before call_next(), read in route handlers and downstream middleware. Never mutate request.state in route handlers (middleware should own state). Use Pydantic model for type safety: class RequestState(BaseModel): user_id: str; request_id: str. Essential for request-scoped data in FastAPI applications.

Middleware executes in order of registration (first registered = outermost layer), with each middleware's pre-call_next() code running top-down and post-call_next() code running bottom-up. Registration order: app.add_middleware(AuthMiddleware); app.add_middleware(LoggingMiddleware). Execution flow: AuthMiddleware before call_next() → LoggingMiddleware before call_next() → Route Handler → LoggingMiddleware after call_next() → AuthMiddleware after call_next(). This means: First-registered middleware (AuthMiddleware) wraps all others, runs first in request phase, runs last in response phase. request.state accessibility: Properties set in middleware are accessible to ALL downstream middleware and route handler. Example: class AuthMiddleware(BaseHTTPMiddleware): async def dispatch(self, request, call_next): request.state.user = await authenticate(request); response = await call_next(request); return response. class RateLimitMiddleware(BaseHTTPMiddleware): async def dispatch(self, request, call_next): user = request.state.user; # Available because AuthMiddleware ran first. Registration order matters: If RateLimitMiddleware registered BEFORE AuthMiddleware, request.state.user would be undefined (AttributeError). Correct order: app.add_middleware(AuthMiddleware) THEN app.add_middleware(RateLimitMiddleware). Built-in middleware order: CORSMiddleware should be outermost (first registered) to handle preflight OPTIONS, TrustedHostMiddleware near outer layer for security, GZipMiddleware near inner layer to compress after business logic, SessionMiddleware before any middleware reading session, AuthMiddleware before any middleware needing user context. Example production order: app.add_middleware(CORSMiddleware); app.add_middleware(TrustedHostMiddleware); app.add_middleware(SessionMiddleware); app.add_middleware(AuthMiddleware); app.add_middleware(RateLimitMiddleware). Debugging: Log in middleware to verify execution order: logger.info(f'{self.__class__.__name__} before'); await call_next(); logger.info(f'{self.__class__.__name__} after'). Output shows stack execution. Best practice: (1) Register security middleware outermost (CORS, TrustedHost). (2) Session middleware before auth. (3) Auth before business logic middleware. (4) Logging middleware can be anywhere depending on what you want to log. (5) Document middleware dependencies in comments. Essential for predictable middleware behavior in FastAPI.