FastAPI Clerk Auth

0.0.9 verified Sat May 09 auth: no python

FastAPI middleware for Clerk authentication. Version 0.0.9 released 2025-01-30. Supports JWT verification, RS256, and request state. Active development, weekly releases.

pip install fastapi-clerk-auth

Common errors

error ImportError: cannot import name 'ClerkAuthMiddleware' from 'fastapi_clerk_auth' ↓

cause Wrong import path; the middleware is in a submodule.

fix

Use: from fastapi_clerk_auth.middleware import ClerkAuthMiddleware

error jwt.exceptions.InvalidIssuerError: Invalid issuer ↓

cause The issuer URL provided does not match the issuer in the JWT token.

fix

Copy the exact issuer from your Clerk dashboard (e.g., https://your-app.clerk.accounts.dev) and ensure no trailing slash.

error ModuleNotFoundError: No module named 'cryptography' ↓

cause Missing dependency for RS256 JWT decoding.

fix

pip install cryptography

Warnings

breaking In v0.0.7, the config attribute 'verify_iat' was added; default is True. If you previously relied on skipping iat verification, you must now set verify_iat=False explicitly. ↓

fix Add verify_iat=False to ClerkConfig if needed.

deprecated The 'leeway' parameter in ClerkConfig is now of type float (v0.0.8). Passing an integer will not break code but may cause type warnings. ↓

fix Use float values for leeway, e.g., leeway=5.0.

gotcha The issuer URL must exactly match the one from your Clerk instance, including trailing slash? No, but https is required. Also the API key must be from Clerk's 'API Keys' section, not the secret key from JWT templates. ↓

fix Ensure issuer ends with '.clerk.accounts.dev' (no trailing slash) and use the API key, not a JWT template secret.

gotcha If you use RS256 (default), you must have the 'cryptography' library installed. The middleware does not install it as a hard dependency, so missing it will raise an ImportError. ↓

fix Install cryptography: pip install cryptography

Imports

ClerkAuthMiddleware

wrong

from fastapi_clerk_auth import ClerkAuthMiddleware

correct

from fastapi_clerk_auth.middleware import ClerkAuthMiddleware

Module structure requires explicit middleware import

ClerkConfig

wrong

from fastapi_clerk_auth import ClerkConfig

correct

from fastapi_clerk_auth.config import ClerkConfig

Config class resides in config module

ClerkClaims

from fastapi_clerk_auth.claims import ClerkClaims

Quickstart

Protect a FastAPI route with Clerk JWT authentication. The decoded token is available via request.state.clerk_auth.

from fastapi import FastAPI, Request
from fastapi_clerk_auth.middleware import ClerkAuthMiddleware
from fastapi_clerk_auth.config import ClerkConfig

app = FastAPI()

clerk_config = ClerkConfig(
    api_key="your_api_key",  # Or set env CLERK_API_KEY
    issuer="https://your-issuer.clerk.accounts.dev",
)
app.add_middleware(ClerkAuthMiddleware, config=clerk_config)

@app.get("/protected")
async def protected(request: Request):
    return {"user": request.state.clerk_auth}