The auth0-python SDK is a Python client library for Auth0's Authentication and Management APIs. It provides developers with programmatic access to Auth0's identity platform for both authenticating users (via the Authentication API) and managing Auth0 resources such as users, organizations, clients, and roles (via the Management API v2). The SDK supports Python 3.8+ and offers both synchronous and asynchronous execution modes.
Scope of this page: This page provides a high-level architectural overview of the SDK structure, main components, and design patterns. For detailed information about specific subsystems, refer to:
Sources: README.md1-190 auth0/__init__.py1-7
The SDK is published to PyPI as auth0-python and provides a complete Python interface to Auth0 services. The package is organized into two primary APIs:
auth0.authentication): Components for user authentication, token acquisition via OAuth 2.0 flows, and JWT verificationauth0.management): Components for managing Auth0 tenant resources via the Management API v2Both APIs share common infrastructure including HTTP clients (RestClient, AsyncRestClient), exception handling (Auth0Error, RateLimitError, TokenValidationError), and telemetry.
Sources: auth0/__init__.py1-7 README.md14-82 auth0/management/__init__.py1-73
The SDK exposes different entry points depending on the use case:
The Authentication API is organized into component classes that mirror Auth0's API structure:
| Component | Class | Purpose |
|---|---|---|
| Token Acquisition | authentication.GetToken | OAuth 2.0 flows (authorization code, client credentials, password realm, refresh token, etc.) |
| Database Authentication | authentication.Database | User signup/login with database connections |
| Passwordless | authentication.Passwordless | Authentication via SMS/email OTP |
| Backchannel Login | authentication.BackChannelLogin | CIBA (Client Initiated Backchannel Authentication) flow |
| Pushed Authorization | authentication.PushedAuthorizationRequests | PAR (Pushed Authorization Requests) flow |
| Social Authentication | authentication.Social | Social provider authentication |
Sources: README.md29-51 README.md85-97
The Management API is accessed through a single facade class:
from auth0.management import Auth0
auth0 = Auth0(domain='myaccount.auth0.com', token='MGMT_API_TOKEN')
The Auth0 class aggregates 30+ endpoint-specific classes as attributes (e.g., auth0.users, auth0.organizations, auth0.clients). Each endpoint class handles a specific resource type in the Management API v2.
Sources: README.md54-79 auth0/management/auth0.py42-101
Diagram 1: SDK Component Architecture mapping high-level concepts to actual Python modules and classes. The auth0.authentication package contains authentication flow classes, auth0.management contains the Auth0 facade and endpoint classes, and auth0.rest provides HTTP infrastructure.
Sources: auth0/management/auth0.py1-101 auth0/management/__init__.py1-73 README.md85-133
The Auth0 class at auth0/management/auth0.py42-101 implements the facade pattern, instantiating all 30+ Management API endpoint classes as attributes:
Diagram 2: The Auth0 facade class aggregates all Management API endpoint classes as instance attributes. Each endpoint class is instantiated in auth0/management/auth0.py59-100 with the same domain, token, and optional rest_options parameters, ensuring consistent configuration across all API calls.
Sources: auth0/management/auth0.py42-101 auth0/test/management/test_auth0.py37-137
The SDK provides both synchronous and asynchronous execution paths:
| Execution Mode | Classes | HTTP Library | Module |
|---|---|---|---|
| Synchronous | auth0.management.Auth0, auth0.authentication.GetToken, etc. | requests | auth0/rest.py |
| Asynchronous | auth0.management.AsyncAuth0, auth0.rest_async.AsyncRestClient | aiohttp | auth0/rest_async.py |
The appropriate Auth0 class is conditionally exported at auth0/management/__init__.py34-37 based on whether aiohttp is available. The async implementation uses an asyncify decorator that wraps synchronous classes and adds *_async method variants (e.g., get_async(), post_async()).
Sources: auth0/management/__init__.py34-37 README.md1-190
The SDK's HTTP layer is built on two complementary client implementations:
| Class | Module | HTTP Library | Key Methods |
|---|---|---|---|
RestClient | auth0/rest.py | requests | get(), post(), patch(), put(), delete() |
AsyncRestClient | auth0/rest_async.py | aiohttp | get_async(), post_async(), patch_async(), put_async(), delete_async() |
RestClientOptions | auth0/rest.py | N/A | Configuration: timeout, retries, telemetry |
Both clients implement:
Authorization: Bearer {token} headerAuth0-Client with SDK version and Python version)The SDK defines three exception classes exported from auth0/__init__.py4-6:
Auth0Error: Base exception for HTTP errors (status_code >= 400), contains full response detailsRateLimitError: Subclass for HTTP 429 responses, adds reset_at timestamp from x-ratelimit-reset headerTokenValidationError: Separate hierarchy for JWT validation failures (signature, claims, expiration)Sources: auth0/__init__.py4-6 README.md1-190
The SDK version at auth0/__init__.py1-2 is dynamically determined at build time using poetry-dynamic-versioning:
This approach ensures version consistency across package metadata, PyPI distribution, and runtime introspection via auth0.__version__.
The SDK follows Python's official support schedule:
| SDK Version | Python Versions | Support Period |
|---|---|---|
| 4.x (current) | 3.9, 3.10, 3.11, 3.12 | Oct 2025 - Oct 2028 |
| 4.6.1 | 3.7+ (last version supporting 3.7) | Deprecated |
| 3.x | 2.0 - 3.6 | End of life |
Python 3.7 support was dropped in version 4.7.0 as documented in CHANGELOG.md75-79 See Page 1.2 (Versioning and Changelog) for detailed version history.
Sources: auth0/__init__.py1-2 README.md134-154 CHANGELOG.md75-79
The SDK has four core dependencies managed via Poetry:
| Dependency | Purpose | Used By |
|---|---|---|
requests >= 2.32.3 | Synchronous HTTP client | auth0.rest.RestClient |
aiohttp >= 3.10.11 | Asynchronous HTTP client | auth0.rest_async.AsyncRestClient |
pyjwt >= 2.8.0 | JWT encoding/decoding | auth0.authentication.TokenVerifier |
cryptography >= 43.0.1 | RSA/HMAC cryptographic operations | JWT signature verification |
The cryptography dependency is explicitly declared because pyjwt has it as an optional dependency, but the SDK requires it for asymmetric signature verification. See Page 1.1 (Installation and Dependencies) for detailed dependency information.
Sources: README.md25 README.md134-154
The SDK uses Poetry for dependency management with PEP 517 compliant packaging:
poetry-core specified in pyproject.tomlpoetry-dynamic-versioning plugin.tar.gz (source distribution) and .whl (wheel) uploaded to PyPIThe development workflow enforces code quality via:
black (formatting), flake8 (linting), isort (import sorting)See Page 4 (Development and Contributing) for detailed development procedures and Page 4.6 (Release Process) for release workflows.
Sources: CHANGELOG.md1-511 README.md19-26 DEVELOPMENT.rst1-35 publish.sh1-7
The SDK implements a three-layer security scanning approach integrated into CI/CD:
| Scanner | Type | Schedule | Purpose |
|---|---|---|---|
| CodeQL | Static code analysis | Weekly | Detect security vulnerabilities in Python code |
| Snyk | Dependency scanning | Twice monthly | Identify vulnerable dependencies |
| ReversingLabs RL-Scanner | Binary analysis | On release | Final security gate before PyPI publication |
Security updates are regularly released to address CVEs, as seen in recent updates to cryptography dependency in CHANGELOG.md63-73 See Page 4.4 (Security Scanning) for detailed scanning procedures.
Sources: CHANGELOG.md1-511
The Management API endpoint classes follow a consistent pattern. Example from NetworkAcls:
This pattern is consistent across all 30+ endpoint classes, making the API predictable and easy to learn.
Sources: auth0/management/network_acls.py9-138 auth0/test/management/test_network_acls.py1-90
Refresh this wiki