npx skills add ...
npx skills add auth0/agent-skills --skill auth0-fastapi-api
npx skills add auth0/agent-skills --skill auth0-fastapi-api
Use when protecting FastAPI endpoints with JWT Bearer token validation, scope checks, or DPoP binding. Integrates auth0-fastapi-api for stateless APIs receiving access tokens — use even if the user says "secure my FastAPI endpoints" or "validate tokens in FastAPI".
Protect FastAPI API endpoints with JWT access token validation using auth0-fastapi-api.
Note: This SDK is currently in beta. The API surface may change before the stable 1.0 release. Check PyPI for the latest version. Requires Python >= 3.9 and FastAPI >= 0.115.11.
auth0-quickstart skill firstauth0-react, auth0-vue, or auth0-angular for client-side authauth0-react-native or auth0-androidYou need an API (not Application) in Auth0.
STOP — ask the user before proceeding.
Ask exactly this question and wait for their answer before doing anything else:
"How would you like to create the Auth0 API resource?
- Automated — I'll run Auth0 CLI scripts that create the resource and write the exact values to your
.envautomatically.- Manual — You create the API yourself in the Auth0 Dashboard (or via
auth0 apis create) and provide me the Domain and Audience.Which do you prefer? (1 = Automated / 2 = Manual)"
Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
If the user chose Automated, follow the Setup Guide [blocked] for complete CLI scripts. The automated path writes .env for you — skip Step 3 below and proceed directly to Step 4.
If the user chose Manual, follow the Setup Guide [blocked] (Manual Setup section) for full instructions. Then continue with Step 3 below.
Quick reference for manual API creation:
Or create manually in Auth0 Dashboard → Applications → APIs
Create .env:
AUTH0_DOMAIN is your Auth0 tenant domain (without https://). AUTH0_AUDIENCE is the API identifier you set when creating the API resource in Auth0.
Create one Auth0FastAPI instance per application and reuse it across routes. Never hardcode the domain or audience — always use environment variables.
The require_auth() dependency validates the Bearer token, verifies the issuer and audience, and returns the decoded JWT claims.
Error responses:
invalid_request — Missing or malformed Authorization headerinvalid_token — Expired token, invalid signature, wrong issuer/audienceinsufficient_scope — Valid token but missing required scopesinternal_server_error — Unexpected errorsResponse body format: {"detail": {"error": "...", "error_description": "..."}}
require_auth(scopes=...) checks the scope claim in the JWT. All specified scopes must be present (AND logic). Missing scopes return 403.
The decoded JWT claims are returned directly from the dependency:
Key claims:
claims["sub"] — user/client IDclaims["scope"] — space-separated granted scopesclaims["iss"] — issuer (your Auth0 domain URL)claims["aud"] — audienceclaims["exp"] — expiration timestampclaims["iat"] — issued-at timestampGet a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.
| Mistake | Fix |
|---|---|
Hardcoding domain or audience in source | Always read from environment variables — never embed credentials in code |
Using python-jose or PyJWT directly | Not needed; auth0-fastapi-api handles all validation via JWKS |
Manually parsing Authorization header | The SDK extracts and validates the token automatically |
Calling jwt.decode() manually | The SDK verifies tokens against the JWKS endpoint — do not verify yourself |
Using fastapi-users for Auth0 JWT validation | That package is for user management, not Auth0 JWT verification |
| Created an Application instead of an API in Auth0 | Must create an API resource (Applications → APIs) — an Application doesn't issue access tokens with the right audience |
Passing domain as full URL with https:// | domain should be the bare domain, e.g. my-tenant.us.auth0.com, not https://my-tenant.us.auth0.com |
| Using an ID token instead of an access token | Must use the access token for API auth — ID tokens are for the client app, not for API authorization |
| Not configuring CORS for SPA clients | Add CORSMiddleware to allow requests from your frontend origin |
os.getenv() returns None silently | Ensure python-dotenv is installed and load_dotenv() is called before Auth0FastAPI() initialization — or use os.environ[] to fail fast |
Built-in proof-of-possession token binding per RFC 9449. DPoP is enabled by default in mixed mode (accepts both Bearer and DPoP tokens). See Integration Guide [blocked] for configuration.
auth0-quickstart - Basic Auth0 setup and framework detectionauth0-mfa - Add Multi-Factor Authenticationauth0-cli - Manage Auth0 resources from the terminalAuth0FastAPI configuration:
Route protection:
Accessing claims:
Environment variables:
AUTH0_DOMAIN — your Auth0 tenant domain (e.g. tenant.us.auth0.com)AUTH0_AUDIENCE — your API identifier (e.g. https://api.example.com)Common Use Cases:
Depends(auth0.require_auth()) (see Step 5)Depends(auth0.require_auth(scopes="...")) (see Step 6)import os
from fastapi import FastAPI, Depends
from fastapi_plugin import Auth0FastAPI
from dotenv import load_dotenv
load_dotenv()
app = FastAPI()
auth0 = Auth0FastAPI(
domain=os.getenv("AUTH0_DOMAIN"),
audience=os.getenv("AUTH0_AUDIENCE"),
)# Require any valid access token
@app.get("/api/private")
async def private(claims: dict = Depends(auth0.require_auth())):
return {"user": claims["sub"]}
# No authentication required
@app.get("/api/public")
async def public():
return {"message": "Public endpoint"}# Requires the read:messages scope
@app.get("/api/messages")
async def get_messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
return {"messages": []}
# Requires both read:data and write:data scopes
@app.post("/api/data")
async def write_data(claims: dict = Depends(auth0.require_auth(scopes=["read:data", "write:data"]))):
return {"created": True}@app.get("/api/profile")
async def profile(claims: dict = Depends(auth0.require_auth())):
return {
"sub": claims["sub"], # user ID
"scope": claims.get("scope"), # granted scopes
}@app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
async def protected():
return {"message": "You need a valid access token to see this."}# No token — expect 401
curl http://localhost:8000/api/private
# With a valid access token
curl http://localhost:8000/api/private \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"auth0 = Auth0FastAPI(
domain=os.getenv("AUTH0_DOMAIN"), # required (or use domains)
audience=os.getenv("AUTH0_AUDIENCE"), # required
dpop_enabled=True, # default; set False for Bearer-only
dpop_required=False, # default; set True to reject Bearer tokens
)Depends(auth0.require_auth()) # any valid token
Depends(auth0.require_auth(scopes="read:res")) # single scope
Depends(auth0.require_auth(scopes=["r", "w"])) # all scopes requiredclaims["sub"] # user/client ID
claims["scope"] # space-separated scopes