Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

The auth0-api-python library allows you to secure APIs running on Python, particularly for verifying Auth0-issued access tokens.

It’s intended as a foundation for building more framework-specific integrations (e.g., with FastAPI, Django, etc.), but you can also use it directly in any Python server-side environment.

Release Downloads License

📚 Documentation - 🚀 Getting Started - 💬 Feedback

Features & Authentication Schemes

This SDK provides comprehensive support for securing APIs with Auth0-issued access tokens:

Authentication Schemes

  • Bearer Token Authentication - Traditional OAuth 2.0 Bearer tokens (RS256)
  • DPoP Authentication - Enhanced security with Demonstrating Proof-of-Possession (ES256)
  • Mixed Mode Support - Seamlessly handles both Bearer and DPoP in the same API

Core Features

  • Unified Entry Point: verify_request() - automatically detects and validates Bearer or DPoP schemes
  • Multi-Custom Domain (MCD) - Accept tokens from multiple Auth0 domains with static lists or dynamic resolvers
  • Organization Policy - Enforce and optionally allowlist the org_id claim on incoming tokens
  • OIDC Discovery - Automatic fetching of Auth0 metadata and JWKS with per-issuer caching
  • JWT Validation - Complete RS256 signature verification with claim validation
  • DPoP Proof Verification - Full RFC 9449 compliance with ES256 signature validation
  • Flexible Configuration - Support for both "Allowed" and "Required" DPoP modes
  • Comprehensive Error Handling - Detailed errors with proper HTTP status codes and WWW-Authenticate headers
  • Framework Agnostic - Works with FastAPI, Django, Flask, or any Python web framework

Documentation

  • Docs Site - explore our docs site and learn more about Auth0.

This library is part of Auth0's Python ecosystem for server-side authentication and API security. Related SDKs:

  • auth0-auth-js - JavaScript/TypeScript monorepo containing:
    • @auth0/auth0-auth-js - Core authentication client (low-level primitives)
    • @auth0/auth0-api-js - Server-side API security (Node.js equivalent of this library)
    • @auth0/auth0-server-js - Server-side web app authentication (session management)

Getting Started

1. Install the SDK

This library requires Python 3.10+.

pip install auth0-api-python

If you’re using Poetry:

poetry install auth0-api-python

2. Create the Auth0 SDK client

Create an instance of the ApiClient. This instance will be imported and used anywhere we need access to the methods.

from auth0_api_python import ApiClient, ApiClientOptions


api_client = ApiClient(ApiClientOptions(
    domain="<AUTH0_DOMAIN>",
    audience="<AUTH0_AUDIENCE>"
))

3. Verify the Access Token

Use the verify_access_token method to validate access tokens. The method automatically checks critical claims like iss, aud, exp, nbf.

import asyncio

from auth0_api_python import ApiClient, ApiClientOptions

async def main():
    api_client = ApiClient(ApiClientOptions(
        domain="<AUTH0_DOMAIN>",
        audience="<AUTH0_AUDIENCE>"
    ))
    access_token = "..."

    decoded_and_verified_token = await api_client.verify_access_token(access_token=access_token)
    print(decoded_and_verified_token)

asyncio.run(main())

In this example, the returned dictionary contains the decoded claims (like sub, scope, etc.) from the verified token.

If the OIDC discovery document or the JWKS request cannot be reached (connection error, timeout, or an HTTP 5xx or 429 response), the method raises AuthServerUnavailableError, a subclass of VerifyAccessTokenError with status 503 and error code auth_server_unavailable. Other fetch failures, such as a 404 or a malformed response, still raise VerifyAccessTokenError. verify_request() raises the same error and sets no WWW-Authenticate header, so clients retry later instead of requesting a new token.

HTTP status codes are checked only for the default HTTP client. With custom_fetch, only a connection error or timeout raised by your function is reported as AuthServerUnavailableError.

This error comes from token verification only. Where verification is skipped, such as get_client_credentials_token() or an exchange with verified=, a failed discovery request raises the underlying httpx error.

4. 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:

import asyncio

from auth0_api_python import ApiClient, ApiClientOptions

async def main():
    api_client = ApiClient(ApiClientOptions(
        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

    await api_client.verify_access_token(access_token) # Verify first so the organization policy applies
    connection_access_token = await 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())

When a token_store is configured on ApiClientOptions, the connection token is cached by caller, connection and login_hint, skipping the exchange on repeat calls. Pass verified= with a VerifiedToken built from the verify_access_token() claims to reuse that verification rather than verifying a second time. See Access Token for a Connection for a full example and setup requirements.

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

5. Custom Token Exchange (Early Access)

This feature requires a confidential client (both client_id and client_secret must be configured).

Custom Token Exchange allows you to exchange a subject token for Auth0 tokens using RFC 8693. This is useful for:

  • Getting Auth0 tokens for another audience
  • Integrating external identity providers
  • Migrating to Auth0
import asyncio

from auth0_api_python import ApiClient, ApiClientOptions

async def main():
    api_client = ApiClient(ApiClientOptions(
        domain="<AUTH0_DOMAIN>",
        audience="<AUTH0_AUDIENCE>",
        client_id="<AUTH0_CLIENT_ID>",
        client_secret="<AUTH0_CLIENT_SECRET>",
        timeout=10.0  # Optional: HTTP timeout in seconds (default: 10.0)
    ))

    subject_token = "..."  # Token from your legacy system or external source

    result = await api_client.get_token_by_exchange_profile(
        subject_token=subject_token,
        subject_token_type="urn:example:subject-token",
        audience="https://api.example.com",  # Optional - omit if your Action or tenant configuration sets the audience
        scope="openid profile email",  # Optional
        requested_token_type="urn:ietf:params:oauth:token-type:access_token"  # Optional
    )

    # Result contains access_token, expires_in, expires_at
    # id_token, refresh_token, and scope are profile/Action dependent (not guaranteed; scope may be empty)

asyncio.run(main())

Important:

  • Client authentication is sent via HTTP Basic (client_id/client_secret), not in the form body.
  • Do not prefix subject_token with "Bearer " - send the raw token value only (checked case-insensitively).
  • The subject_token_type must match a Token Exchange Profile configured in Auth0. This URI identifies which profile will process the exchange and must not use reserved OAuth namespaces (IETF or vendor-controlled). Use your own collision-resistant namespace. See the Custom Token Exchange documentation for naming guidance.
  • If neither an explicit audience nor tenant/Action logic sets it, you may receive a token not targeted at your API.

Additional Parameters

You can pass additional parameters for your Token Exchange Profile or Actions via the extra parameter. These are sent as form fields to Auth0 and may be inspected by Actions:

result = await api_client.get_token_by_exchange_profile(
    subject_token=subject_token,
    subject_token_type="urn:example:subject-token",
    audience="https://api.example.com",
    extra={
        "device_id": "device-12345",
        "session_id": "sess-abc"
    }
)

Error Handling

from auth0_api_python import GetTokenByExchangeProfileError, ApiError

try:
    result = await api_client.get_token_by_exchange_profile(
        subject_token=subject_token,
        subject_token_type="urn:example:subject-token"
    )
except GetTokenByExchangeProfileError as e:
    # Validation errors (invalid token format, missing credentials, reserved params, etc.)
    print(f"Validation error: {e}")
except ApiError as e:
    # Token endpoint errors (invalid_grant, network issues, malformed responses, etc.)
    print(f"API error: {e.code} - {e.message} (status: {e.status_code})")

Related SDKs: auth0-auth-js (see @auth0/auth0-api-js package for Node.js equivalent)

More info: https://auth0.com/docs/authenticate/custom-token-exchange

On Behalf Of Token Exchange

Use get_token_on_behalf_of() when your API receives an Auth0 access token for itself and needs to exchange it for another Auth0 access token targeting a downstream API while preserving the same user identity. This is especially useful for MCP servers and other intermediary APIs that need to call downstream APIs on behalf of the user.

The following example verifies the incoming access token for your API, exchanges it for a token for the downstream API, and then calls the downstream API with the exchanged token.

import httpx

async def handle_calendar_request(incoming_access_token: str):
    await api_client.verify_access_token(access_token=incoming_access_token)

    result = await api_client.get_token_on_behalf_of(
        access_token=incoming_access_token,
        audience="https://calendar-api.example.com",
        scope="calendar:read calendar:write"
    )

    async with httpx.AsyncClient() as client:
        downstream_response = await client.get(
            "https://calendar-api.example.com/events",
            headers={"Authorization": f"Bearer {result['access_token']}"}
        )

    downstream_response.raise_for_status()

    return downstream_response.json()

The OBO wrapper reuses the existing RFC 8693 exchange support and fixes both token-type parameters to Auth0 access-token exchange. In the current implementation, the SDK forwards the incoming access token as the subject_token and relies on Auth0 to handle any DPoP-specific behavior for that token. The OBO result only includes access-token-oriented fields. It does not expose id_token or refresh_token.

Configuring a token_store on ApiClientOptions caches the exchanged token, so a repeat call for the same caller, audience, organization, scopes, and session reuses it instead of exchanging again. With no token_store, every call performs a fresh exchange, matching the existing behavior above.

Client Credentials for Server-to-Server Calls

Use get_client_credentials_token() to obtain an M2M access token for server-to-server calls using the OAuth 2.0 client credentials grant.

result = await api_client.get_client_credentials_token(
    audience="https://downstream-api.example.com",
    scope="read:data",
)
# call downstream API with result["access_token"]

See the Client Credentials example for a full example that calls a downstream API, plus the caching behavior.

Inspecting Delegation After Token Verification

When a downstream API or MCP server receives an access token that may have been issued through delegation, it can verify the token first and then inspect the act claim to identify the current actor for authorization and the full delegation chain for logging or audit.

import logging

from auth0_api_python import (
    ApiClient,
    ApiClientOptions,
    get_current_actor,
    get_delegation_chain,
)

logger = logging.getLogger(__name__)

api_client = ApiClient(ApiClientOptions(
    domain="<AUTH0_DOMAIN>",
    audience="<AUTH0_AUDIENCE>",
))

async def authorize_delegated_request(access_token: str):
    claims = await api_client.verify_access_token(access_token=access_token)

    current_actor = get_current_actor(claims)
    delegation_chain = get_delegation_chain(claims)

    if current_actor != "mcp_server_client_id":
        raise PermissionError("unexpected actor")

    logger.info(
        "delegated request",
        extra={
            "user_sub": claims["sub"],
            "current_actor": current_actor,
            "delegation_chain": delegation_chain,
        },
    )

    return claims

Only the outermost act.sub represents the current actor and should be used for authorization decisions. Nested act values represent prior actors in the delegation chain and are better suited for logging, audit, or attribution.

Requiring Additional Claims

If your application demands extra claims, specify them with required_claims:

decoded_and_verified_token = await api_client.verify_access_token(
    access_token=access_token,
    required_claims=["my_custom_claim"]
)

If the token lacks my_custom_claim or fails any standard check (issuer mismatch, expired token, invalid signature), the method raises a VerifyAccessTokenError.

6. DPoP Authentication

This library supports DPoP (Demonstrating Proof-of-Possession) for enhanced security, allowing clients to prove possession of private keys bound to access tokens.

Allowed Mode (Default)

Accepts both Bearer and DPoP tokens - ideal for gradual migration:

api_client = ApiClient(ApiClientOptions(
    domain="<AUTH0_DOMAIN>",
    audience="<AUTH0_AUDIENCE>",
    dpop_enabled=True,      # Default - enables DPoP support
    dpop_required=False     # Default - allows both Bearer and DPoP
))

# Use verify_request() for automatic scheme detection
result = await api_client.verify_request(
    headers={
        "authorization": "DPoP eyJ0eXAiOiJKV1Q...",  # DPoP scheme
        "dpop": "eyJ0eXAiOiJkcG9wK2p3dC...",        # DPoP proof
    },
    http_method="GET",
    http_url="https://api.example.com/resource"
)

Required Mode

Enforces DPoP-only authentication, rejecting Bearer tokens:

api_client = ApiClient(ApiClientOptions(
    domain="<AUTH0_DOMAIN>",
    audience="<AUTH0_AUDIENCE>", 
    dpop_required=True      # Rejects Bearer tokens
))

Configuration Options

api_client = ApiClient(ApiClientOptions(
    domain="<AUTH0_DOMAIN>",
    audience="<AUTH0_AUDIENCE>",
    dpop_enabled=True,          # Enable/disable DPoP support
    dpop_required=False,        # Require DPoP (reject Bearer)
    dpop_iat_leeway=30,         # Clock skew tolerance (seconds)
    dpop_iat_offset=300,        # Maximum proof age (seconds)
))

7. Multi-Custom Domain (MCD) Support

If your Auth0 tenant has multiple custom domains, or you're migrating between domains, the SDK can accept tokens from any of them:

Static Domain List

from auth0_api_python import ApiClient, ApiClientOptions

api_client = ApiClient(ApiClientOptions(
    domains=[
        "tenant.auth0.com",
        "auth.example.com",
        "auth.acme.org"
    ],
    audience="https://api.example.com"
))

# Tokens from any of the three domains are accepted
claims = await api_client.verify_access_token(access_token)

Dynamic Resolver

For runtime domain resolution based on request context:

from auth0_api_python import ApiClient, ApiClientOptions, DomainsResolverContext

def resolve_domains(context: DomainsResolverContext) -> list[str]:
    # Determine allowed domains based on the request
    return ["tenant.auth0.com", "auth.example.com"]

api_client = ApiClient(ApiClientOptions(
    domains=resolve_domains,
    audience="https://api.example.com"
))

For hybrid mode (migration scenarios), resolver patterns, error handling, and caching configuration, see the full guides:

8. Anonymous Callers

Anonymous Sessions give a visitor an Auth0 identity before they log in. Session creation happens in your web application. This SDK only validates the tokens they produce. The access token is a standard Auth0 Bearer JWT, so verify_access_token() and verify_request() validate it exactly like any other token. The only difference is the sub claim, which starts with anon@.

An anonymous token passes verification by default. Deciding whether an anonymous caller is authorized is your application's responsibility. See Anonymous Callers for allow, block-per-route, and block-globally patterns.

9. Organization Policy

For APIs that need to enforce an Auth0 Organization context on every request, optionally restricted to a specific set of Organizations:

from auth0_api_python import ApiClient, ApiClientOptions

api_client = ApiClient(ApiClientOptions(
    domain="tenant.auth0.com",
    audience="https://api.example.com",
    organization_policy="required",
    organization_id=["org_abc123", "org_def456"]
))

claims = await api_client.verify_access_token(access_token)

See the Organization Policy Guide for policy modes, the allowlist, and error handling.

10. Client Telemetry

The SDK sends an Auth0-Client header and a User-Agent header (Python/<version>) on the requests it makes to Auth0 with its default HTTP client. Requests served by custom_fetch do not carry them. If you build a wrapper SDK on top of this one, pass client_info so the header names your SDK. An invalid client_info raises ConfigurationError when the client is created.

api_client = ApiClient(ApiClientOptions(
    domain="<AUTH0_DOMAIN>",
    audience="<AUTH0_AUDIENCE>",
    client_info={"name": "my-wrapper-sdk", "version": "1.2.3", "env": {"my-framework": "4.5.6"}},
))

Feedback

Contributing

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

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 Logo

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.

Metadata

Release files for auth0-api-python 1.0.0b11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for auth0-api-python 1.0.0b11
File Size Uploaded Provenance Actions
auth0_api_python-1.0.0b11.tar.gz 46.1 kB With provenance Details for auth0_api_python-1.0.0b11.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for auth0-api-python 1.0.0b11
File Interpreter ABI Platform Actions
auth0_api_python-1.0.0b11-py3-none-any.whl Python 3 none any Details for auth0_api_python-1.0.0b11-py3-none-any.whl

Total release size: 93.0 kB

Release files / auth0_api_python-1.0.0b11.tar.gz

Download URL auth0_api_python-1.0.0b11.tar.gz
Size 46.1 kB
Tags Source
SHA-256 checksum
How to use checksums
08216a30c371bf7d716793cb287872e7c6cefc533d8639bddcaba55157e4052d
BLAKE2b-256 checksum
How to use checksums
5ed1556f912f73c5e2c75143c90684cb3f91a93c8378edacea8569ef74d30b40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / auth0_api_python-1.0.0b11-py3-none-any.whl

Download URL auth0_api_python-1.0.0b11-py3-none-any.whl
Size 46.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b1d82997300f83b6874c7a8f4a5fb9ff58fb4c63b83c81d188b278a472d0f72f
BLAKE2b-256 checksum
How to use checksums
1f27b89ba94e31afbbacda307136faa514f42671d63a2ef769296c294609036a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for auth0-api-python 1.0.0b11

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for auth0_api_python-1.0.0b11.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page