auth0-fastapi-api

📚 Documentation - 🚀 Getting Started - 💬 Feedback

Documentation

• QuickStart- our guide for adding Auth0 to your Fastapi app.
• Examples - examples for your different use cases.
• Docs Site - explore our docs site and learn more about Auth0.

Getting Started

1. Install the SDK

This library requires Python 3.9+.

pip install auth0-fastapi-api

If you’re using Poetry:

poetry install auth0-fastapi-api

2. Configure and Register the Auth0FastAPI Plugin

In your FastAPI application, create an instance of the Auth0FastAPI class. Supply the domain and audience from Auth0:

• The AUTH0_DOMAIN can be obtained from the Auth0 Dashboard once you've created an API.
• The AUTH0_AUDIENCE is the identifier of the API that is being called. You can find this in the API section of the Auth0 dashboard.

from fastapi_plugin import Auth0FastAPI

# Create the Auth0 integration
auth0 = Auth0FastAPI(
    domain="<AUTH0_DOMAIN>",
    audience="<AUTH0_AUDIENCE>",
)

3. Protecting API Routes

To protect a FastAPI route, use the require_auth(...) dependency. Any incoming requests must include a valid Bearer token (JWT) in the Authorization header, or they will receive an error response (e.g., 401 Unauthorized).

@app.get("/protected-api")
async def protected(
    # The route depends on require_auth returning the decoded token claims
    claims: dict = Depends(auth0.require_auth())
):
    # `claims` is the verified JWT payload (dict) extracted by the SDK
    return {"message": f"Hello, {claims['sub']}"}

How It Works

• The user sends a request with Authorization: Bearer <JWT>.
• The SDK parses the token, checks signature via Auth0’s JWKS, validates standard claims like iss, aud, exp, etc.
• If valid, the route receives the decoded claims as a Python dict (e.g. {"sub": "user123", "scope": "read:stuff", ...}).

[!IMPORTANT]
This method protects API endpoints using bearer tokens. It does not create or manage user sessions in server-side rendering scenarios. For session-based usage, consider a separate library or approach.

Custom Claims

If your tokens have additional custom claims, you’ll see them in the claims dictionary. For example:

@app.get("/custom")
async def custom_claims_route(claims: dict = Depends(auth0.require_auth())):
    # Suppose your JWT includes { "permissions": ["read:data"] }
    permissions = claims.get("permissions", [])
    return {"permissions": permissions}

You can parse or validate these claims however you like in your application code.

Dependency in the path operation decorator

In case you don't need to use the claims dictionary in your endpoint you can also use the dependency as part of the path decorator. For example:

@app.get("/protected", dependencies=Depends(auth0.require_auth()))
async def protected():
    # Protected endpoint 
    return {"msg": "You need to have an access token to see this endpoint."}

This way you can protected your endpoint and not have an unused variable.

4. Advanced Configuration

• Scopes: If you need to check for specific scopes (like read:data), call require_auth(scopes="read:data") or pass a list of scopes. The SDK will return a 403 if the token lacks those scopes in its scope claim.

@app.get("/read-data")
async def read_data_route(
    claims=Depends(auth0.require_auth(scopes="read:data"))
):
    return {"data": "secret info"}

• Mocking / Testing: To test locally without hitting Auth0’s actual JWKS endpoints, you can mock the HTTP calls using pytest-httpx or patch the verification method to avoid real cryptographic checks.

Example

from fastapi import FastAPI, Depends
from auth0_fastapi_api import Auth0FastAPI
from fastapi.testclient import TestClient

app = FastAPI()
auth0 = Auth0FastAPI(domain="my-tenant.us.auth0.com", audience="my-api")

@app.get("/public")
async def public():
    return {"message": "No token required here"}

@app.get("/secure")
async def secure_route(
    claims: dict = Depends(auth0.require_auth(scopes="read:secure"))
):
    # claims might contain {"sub":"user123","scope":"read:secure"}
    return {"message": f"Hello {claims['sub']}, you have read:secure scope!"}

# Example test
def test_public_route():
    client = TestClient(app)
    response = client.get("/public")
    assert response.status_code == 200
    assert response.json() == {"message": "No token required here"}

5. Get an access token for a connection

If you need to get an access token for an upstream idp via a connection, you can use the get_access_token_for_connection method on the underlying api_client:

import asyncio

from auth0_fastapi_api import Auth0FastAPI

async def main():
    auth0 = Auth0FastAPI(
        domain="<AUTH0_DOMAIN>",
        audience="<AUTH0_AUDIENCE>",
        client_id="<AUTH0_CLIENT_ID>",
        client_secret="<AUTH0_CLIENT_SECRET>",
    )
    connection = "my-connection" # The Auth0 connection to the upstream idp
    access_token = "..." # The Auth0 access token to exchange

    connection_access_token = await auth0.api_client.get_access_token_for_connection({"connection": connection, "access_token": access_token})
    # The returned token is the access token for the upstream idp
    print(connection_access_token)

asyncio.run(main())

More info https://auth0.com/docs/secure/tokens/token-vault

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please read the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines
• This repo's contribution guide

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?

This project is licensed under the MIT license. See the LICENSE file for more info.