Auth0 Fastapi Api

intent

use this skill when you need to protect FastAPI API endpoints with JWT access token validation from Auth0. deploy this for REST APIs receiving tokens from SPAs, mobile apps, or other clients that have already obtained access tokens via an Auth0 authorization flow. scope this to stateless token validation only, not token issuance or user login flows. handles standard Bearer token auth plus optional DPoP proof-of-possession token binding per RFC 9449.

inputs

environment variables (required):

• AUTH0_DOMAIN: your Auth0 tenant domain without https://, e.g. tenant.us.auth0.com
• AUTH0_AUDIENCE: your Auth0 API resource identifier, e.g. https://my-api.example.com

auth0 api resource (required):

• must be an API resource in Auth0 (not an Application). created via Auth0 Dashboard → Applications → APIs or via CLI: auth0 apis create --name "My FastAPI API" --identifier https://my-api.example.com

python dependencies (required):

• fastapi >= 0.115.11
• auth0-fastapi-api >= 1.0.1 (currently beta, API surface may change)
• python-dotenv (for local .env loading)
• python >= 3.9

external connection:

• Auth0 JWKS endpoint (fetched automatically from https://{AUTH0_DOMAIN}/.well-known/jwks.json)
• no explicit API key or OAuth setup needed beyond the domain and audience above

procedure

1. install dependencies: run pip install auth0-fastapi-api python-dotenv to get the SDK and environment loader. verify installation with python -c "import auth0_fastapi_api".

   output: no console output on success, or package installation error if pip fails.

2. create or confirm auth0 api resource: ask the user this exact question and wait for their answer before proceeding: "how would you like to create the auth0 api resource? 1. automated (i'll run auth0 cli scripts that create the resource and write exact values to your .env automatically). 2. 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 default to manual. do not proceed until the user answers.

   input: user choice (1 or 2). output: if 1, automated setup scripts are provided; if 2, user is directed to manual setup instructions.

3. if automated (choice 1): execute auth0 cli commands to create the api resource and write AUTH0_DOMAIN and AUTH0_AUDIENCE to .env file automatically. user does not manually enter env vars.

   input: auth0 cli installed and authenticated. output: .env file written with AUTH0_DOMAIN and AUTH0_AUDIENCE populated.

4. if manual (choice 2): user creates the api resource themselves and provides you the domain (e.g. tenant.us.auth0.com) and audience (e.g. https://my-api.example.com). create .env file with these values:

   AUTH0_DOMAIN=<user-provided-domain>
   AUTH0_AUDIENCE=<user-provided-audience>
   

   input: user-provided domain and audience strings. output: .env file created with auth0 config.

5. initialize auth0fastapi instance: in your fastapi app, load environment variables and create a single reusable Auth0FastAPI instance:

   import os
   from fastapi import FastAPI, Depends
   from auth0_fastapi_api import Auth0FastAPI
   from dotenv import load_dotenv
   
   load_dotenv()
   
   app = FastAPI()
   
   auth0 = Auth0FastAPI(
       domain=os.getenv("AUTH0_DOMAIN"),
       audience=os.getenv("AUTH0_AUDIENCE"),
   )
   

   input: .env file exists with AUTH0_DOMAIN and AUTH0_AUDIENCE set. output: auth0 instance ready to use in route handlers; os.getenv() returns non-None values.

6. protect routes with token validation: add Depends(auth0.require_auth()) to route handlers that require a valid bearer token. the sdk automatically extracts the token from the authorization: bearer <token> header, validates signature and claims against the jwks endpoint, and returns decoded jwt claims as a dict.

   @app.get("/api/private")
   async def private(claims: dict = Depends(auth0.require_auth())):
       return {"user": claims["sub"]}
   

   input: incoming http request with authorization: bearer <access_token> header. output: if token is valid, claims dict is passed to handler; if invalid, sdk returns http error (see output contract).

7. enforce scopes (optional): if a route requires specific oauth scopes, pass them to require_auth(scopes=...). pass a single scope as a string or multiple scopes as a list. all scopes must be present in the token (and logic).

   @app.get("/api/messages")
   async def get_messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
       return {"messages": []}
   
   @app.post("/api/data")
   async def write_data(claims: dict = Depends(auth0.require_auth(scopes=["read:data", "write:data"]))):
       return {"created": True}
   

   input: jwt token with scope claim (space-separated scope string). output: if all required scopes present, claims passed to handler; if missing scopes, sdk returns 403 insufficient_scope error.

8. access decoded claims in handlers: the claims dict returned by require_auth() contains standard jwt claims:

   • claims["sub"]: user or client id
   • claims["scope"]: space-separated granted scopes
   • claims["iss"]: issuer url (your auth0 domain)
   • claims["aud"]: audience (your api identifier)
   • claims["exp"]: token expiration timestamp (unix seconds)
   • claims["iat"]: token issued-at timestamp (unix seconds)

   input: decoded jwt claims dict from sdk. output: handler accesses specific claims and uses them for business logic.

9. protect routes without needing claims: if a route just needs to verify a valid token exists but doesn't use the claims, use dependencies=[Depends(auth0.require_auth())] on the route decorator:

   @app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
   async def protected():
       return {"message": "You need a valid access token to see this."}
   

   input: incoming http request with bearer token. output: token validated; if valid, route handler executes; if invalid, 401 or 400 returned.

10. enable cors for spa clients (if needed): if your api receives requests from a web frontend on a different origin, add fastapi cors middleware:

    from fastapi.middleware.cors import CORSMiddleware
    
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["https://example.com"],
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
    

    input: list of allowed frontend origins. output: api responds with correct cors headers so browser preflight and actual requests succeed.

11. test the api: obtain a test access token (via client credentials flow or auth0 dashboard apis test tab), then send requests:

    curl http://localhost:8000/api/private
    # expect 400 or 401
    
    curl http://localhost:8000/api/private \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    # expect 200 with claims
    

    input: valid access token string. output: if token valid, 200 response with json body; if missing or invalid, 400/401/403 error with json detail.

12. (optional) enable dpop token binding: set dpop_enabled=True (default) in Auth0FastAPI() to accept both bearer and dpop tokens. set dpop_required=True to reject plain bearer tokens and require dpop only:

    auth0 = Auth0FastAPI(
        domain=os.getenv("AUTH0_DOMAIN"),
        audience=os.getenv("AUTH0_AUDIENCE"),
        dpop_enabled=True,
        dpop_required=False,
    )
    

    input: dpop configuration flags. output: sdk validates dpop proofs on incoming requests that include dpop headers; bearer-only requests accepted if dpop_required=False.

decision points

• if user chooses automated setup (step 2, choice 1): run auth0 cli commands to provision the api resource and write .env. skip manual config and move to step 5.

• if user chooses manual setup (step 2, choice 2): user creates the api resource themselves and provides domain/audience. you write .env manually and proceed to step 5.

• if os.getenv("AUTH0_DOMAIN") returns None: .env file not loaded or missing AUTH0_DOMAIN key. ensure load_dotenv() is called before Auth0FastAPI() initialization, or substitute os.environ[] (which raises KeyError and fails fast instead of silently returning None).

• if incoming request has no authorization header: sdk returns 400 invalid_request with error detail.

• if token is expired, malformed, or has invalid signature: sdk returns 401 invalid_token with error detail.

• if token is valid but issuer or audience doesn't match: sdk returns 401 invalid_token with error detail.

• if token is valid but required scopes are missing: sdk returns 403 insufficient_scope with error detail.

• if dpop_required=True but request uses plain bearer token: sdk returns 401 error (dpop proof required).

• if jwks endpoint is unreachable or returns error: sdk caches keys and falls back to cached set. if no cache, sdk raises exception and request fails (network error handling depends on fastapi error middleware).

• if token is valid for a different audience (wrong api resource): sdk returns 401 invalid_token. confirm user is requesting token for the correct api identifier in auth0.

• if using a hardcoded domain or audience in source: this violates the inputs contract. always read from environment variables to avoid embedding credentials.

output contract

on successful token validation:

• http response: 200 (or whatever status the route handler returns)
• response body: whatever json the route handler returns (sdk injects claims dict, handler controls output)
• claims dict passed to handler contains at minimum: sub, scope, iss, aud, exp, iat

on missing or malformed authorization header:

• http response: 400
• response body: {"detail": {"error": "invalid_request", "error_description": "..."}}

on expired, invalid, or forged token:

• http response: 401
• response body: {"detail": {"error": "invalid_token", "error_description": "..."}}

on missing required scopes:

• http response: 403
• response body: {"detail": {"error": "insufficient_scope", "error_description": "..."}}

on unexpected error (e.g. jwks fetch failure):

• http response: 500
• response body: {"detail": {"error": "internal_server_error", "error_description": "..."}}

environment configuration:

• .env file location: project root or directory where load_dotenv() is called
• file format: KEY=value (one per line, no quotes needed unless value contains spaces)

python module:

• Auth0FastAPI class instantiated and reused across all routes in the app
• single instance per app (do not create multiple instances)

outcome signal

• you can call a protected route without a token and receive a 400 or 401 error response.
• you can obtain a valid access token via auth0 dashboard or client credentials flow.
• you call the protected route with authorization: bearer <token> and receive a 200 response with the route handler's json output (including claims data).
• you call a scope-protected route with a token missing required scopes and receive a 403 insufficient_scope response.
• you call a scope-protected route with a token that has all required scopes and receive a 200 response.
• logging or inspection shows the decoded claims dict being passed to the route handler.
• calls from a spa frontend on a different origin succeed (if cors middleware is configured).
• expired or revoked tokens are rejected with 401 invalid_token.

---

common mistakes to avoid

mistake	fix
hardcoding domain or audience in source code	always read from environment variables. never embed credentials. use os.getenv() or os.environ[].
manually parsing the authorization header or calling jwt.decode() directly	the sdk handles header extraction and token validation against jwks. do not verify tokens yourself.
using python-jose or pyjwt to validate tokens	not needed. the sdk handles all validation via jwks endpoint.
creating an auth0 application instead of an api resource	must be an api resource (dashboard → applications → apis). applications don't issue access tokens with the right audience.
passing domain as a full url with https://	domain should be the bare domain, e.g. tenant.us.auth0.com, not https://tenant.us.auth0.com.
using an id token instead of an access token	api auth requires the access token, not the id token. id tokens are for the client app, not api authorization.
not configuring cors for spa clients	add CORSMiddleware if your frontend is on a different origin.
relying on os.getenv() without checking for None	if .env is not loaded or key is missing, os.getenv() returns None silently. use os.environ[] to fail fast, or check the result explicitly.
using fastapi-users for auth0 jwt validation	that package is for user management, not auth0 jwt token verification. use auth0-fastapi-api instead.
calling require_auth() multiple times per route	create a single auth0 instance and reuse it. calling it multiple times is redundant and slower.
skipping scope checks on sensitive routes	always enforce scopes for endpoints that mutate data or expose sensitive info.
not testing with expired tokens	token expiration (the exp claim) is validated by the sdk. verify that expired tokens are rejected with 401.

---

dpop and advanced options

dpop (proof-of-possession) support is enabled by default and compliant with rfc 9449. dpop binds access tokens to a client's public key, preventing token reuse if intercepted. configure via:

auth0 = Auth0FastAPI(
    domain=os.getenv("AUTH0_DOMAIN"),
    audience=os.getenv("AUTH0_AUDIENCE"),
    dpop_enabled=True,     # accept bearer or dpop (default)
    dpop_required=False,   # set true to reject plain bearer tokens
)

if dpop_required=True, only requests with valid dpop proofs are accepted. clients must send the dpop header with a signed jwt. this prevents token theft but is stricter. use only if your clients support it.

see the integration guide (references/integration.md#dpop-support) for dpop client implementation examples.

---

related skills

• auth0-quickstart: basic auth0 setup and framework detection.
• auth0-mfa: add multi-factor authentication to your app.
• auth0-cli: manage auth0 resources from the terminal.

---

quick reference

auth0fastapi configuration:

auth0 = Auth0FastAPI(
    domain=os.getenv("AUTH0_DOMAIN"),      # required
    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
)

route protection:

Depends(auth0.require_auth())                       # any valid token
Depends(auth0.require_auth(scopes="read:resource")) # single scope
Depends(auth0.require_auth(scopes=["r", "w"]))      # multiple scopes (and logic)

accessing claims:

claims["sub"]     # user or client id
claims["scope"]   # space-separated scopes
claims["iss"]     # issuer (auth0 domain url)
claims["aud"]     # audience (api identifier)
claims["exp"]     # expiration timestamp
claims["iat"]     # issued-at timestamp

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 patterns:

• protect a route: Depends(auth0.require_auth()) (see step 6)
• enforce scopes: Depends(auth0.require_auth(scopes="...")) (see step 7)
• dpop token binding: set dpop_required=True (see advanced options)
• cors for spas: use CORSMiddleware (see step 10)
• testing: use auth0 dashboard apis test tab