API Security & OAuth2 PKCE

Learning outcomes

• Secure API endpoints with OAuth2 PKCE and JWT claims
• Enforce role-based access control contracts

Mental model

OAuth2 PKCE (Proof Key for Code Exchange) secures client authentication without exposing client secrets, while JWT (JSON Web Tokens) provides stateless, cryptographically signed authorization payloads across microservices.

Theory

• OAuth2 PKCE: Prevents authorization code injection attacks by requiring a dynamic code_verifier matching the pre-hashed code_challenge.
• JWT (Header.Payload.Signature): Stateless tokens signed using asymmetric cryptography (RS256/ES256). API gateways and services verify signatures using Public Keys (JWKS endpoint) without querying database sessions.

import jwt
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\n..."

def verify_jwt_token(token: str = Depends(oauth2_scheme)) -> dict:
    try:
        payload = jwt.decode(token, PUBLIC_KEY, algorithms=["RS256"], audience="api://default")
        return payload
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Token expired")
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")

Alternatives and trade-offs

• Stateful Session Cookies: Centralized revocation on server DB; requires database session lookups on every API request.
• Stateless JWT Tokens: Fast distributed validation via public keys; immediate token revocation requires maintaining a Redis token revocation blocklist (JTI).

Failure modes and misconceptions

1. Symmetric Secret Key Insecurity: Using HS256 (shared secret) forces microservices to hold the private secret key to verify tokens. Use RS256/ES256 asymmetric keys so services only require public keys.
2. Missing Token Expiration (exp): Issuing JWT tokens without strict exp claims allows stolen tokens to grant access indefinitely.

Decision scenario

Implement OAuth2 PKCE with RS256-signed JWT access tokens for single-page applications (SPAs) and mobile clients to ensure secure authentication without embedded secrets.

Learning outcomes

• Structure OAuth2 PKCE authorization flows for public client applications.
• Verify JWT signatures asynchronously using public key sets (JWKS).
• Enforce role-based access scopes in FastAPI dependency injection pipelines.

Trade-offs

Stateless JWT tokens enable high-speed distributed verification, but require short TTLs and revocation lists to handle compromised accounts.

Primary sources

• FastAPI Framework Architecture & Dependency Injection Specification — Tiangolo, verified 2026-07-22