The auth0-python SDK is a Python client library for Auth0's Authentication and Management APIs. Version 5.0 represents a major architectural rewrite with distinct implementations for each API:
auth0.authentication): Maintains backward compatibility from v4.x, providing OAuth 2.0 flows, token acquisition, and JWT verificationauth0.management): Completely rewritten in v5.0 using Fern code generation from Auth0's OpenAPI specifications, featuring modular sub-clients, Pydantic type safety, and automatic token managementThe SDK supports Python 3.8+ (Python 3.7 support dropped in v5.0) and provides both synchronous and asynchronous execution modes through parallel client implementations.
Scope of this page: This page provides a high-level architectural overview of the SDK structure, main components, and the v5.0 rewrite. For detailed information about specific subsystems, refer to:
Sources: README.md1-40 CHANGELOG.md3-40
The SDK is published to PyPI as auth0-python and provides a complete Python interface to Auth0 services. The v5.0 release introduced a fundamental architectural split:
Authentication API (auth0.authentication): User authentication, token acquisition via OAuth 2.0/OIDC flows, JWT verification, and passwordless authentication. Uses requests (sync) and aiohttp (async) HTTP clients. Fully backward compatible with v4.x.
Management API v5 (auth0.management): Complete rewrite generated from Auth0's OpenAPI specifications using Fern. Features modular sub-clients (20+ resource-specific clients), Pydantic models for type safety, and unified httpx HTTP client for both sync and async. Breaking changes from v4.x.
The dual structure allows existing Authentication API code to run unchanged while Management API code requires migration to the new v5 API surface.
Sources: README.md1-40 CHANGELOG.md3-40
The SDK provides different entry points optimized for each API:
The Authentication API maintains its v4.x structure with component classes:
| Component | Class | Purpose |
|---|---|---|
| Token Acquisition | auth0.authentication.GetToken | OAuth 2.0 flows (client credentials, authorization code, password realm, refresh token) |
| Token Verification | auth0.authentication.TokenVerifier, AsyncTokenVerifier | JWT signature and claims validation |
| Database Authentication | auth0.authentication.Database | User signup/login with database connections |
| Passwordless | auth0.authentication.Passwordless | Authentication via SMS/email OTP |
| Backchannel Login | auth0.authentication.BackChannelLogin | CIBA (Client Initiated Backchannel Authentication) flow with RAR support |
| Pushed Authorization | auth0.authentication.PushedAuthorizationRequests | PAR (Pushed Authorization Requests) flow |
Sources: README.md48-66 CHANGELOG.md38
Version 5.0 introduced two client hierarchies:
Recommended: High-level clients with automatic token management:
Advanced: Base clients with manual token management:
The ManagementClient and AsyncManagementClient classes provide the same sub-client structure as Auth0/AsyncAuth0 but with simplified initialization (domain instead of full base_url) and optional automatic token lifecycle management.
Sources: README.md69-107 CHANGELOG.md17-23
Diagram 1: Dual Architecture Split
Version 5.0 maintains the Authentication API with its original stack (requests/aiohttp, Auth0Error exceptions) while the Management API uses a completely new stack (httpx, Pydantic, ApiError exceptions) generated from OpenAPI specifications.
Sources: CHANGELOG.md3-40 README.md48-157
Diagram 2: Sub-Client Hierarchy
The v5 Management API uses modular sub-clients where each resource type (users, organizations, actions, etc.) is exposed as an attribute on the main client. Each sub-client provides resource-specific methods that accept and return Pydantic-validated models.
Sources: README.md69-157 CHANGELOG.md10-27
The Management API v5 provides 20+ modular sub-clients accessible as attributes on ManagementClient, AsyncManagementClient, Auth0, and AsyncAuth0:
| Sub-Client Attribute | Resource Type | Key Operations |
|---|---|---|
client.actions | Actions | Manage Auth0 Actions (custom code for extensibility) |
client.attack_protection | Attack Protection | Configure brute force, suspicious IP, and breached password detection |
client.branding | Branding | Customize tenant branding, themes, and templates |
client.client_credentials | Client Credentials | Manage client credential authentication methods |
client.client_grants | Client Grants | Configure client grant permissions |
client.clients | Clients | Manage applications (SPAs, web apps, M2M apps) |
client.connections | Connections | Configure identity providers and database connections |
client.custom_domains | Custom Domains | Manage custom domain configurations |
client.device_credentials | Device Credentials | Manage device credential rotation |
client.email_templates | Email Templates | Customize transactional emails |
client.grants | Grants | Manage user grants |
client.guardian | Guardian | Configure MFA settings |
client.hooks | Hooks | Manage extensibility hooks (legacy) |
client.jobs | Jobs | Manage asynchronous jobs (user imports, exports) |
client.log_streams | Log Streams | Configure log streaming to external services |
client.logs | Logs | Query tenant activity logs |
client.organizations | Organizations | Manage B2B organizations |
client.prompts | Prompts | Customize Universal Login prompts |
client.resource_servers | APIs | Register and configure APIs |
client.roles | Roles | Manage RBAC roles |
client.stats | Statistics | Retrieve tenant usage statistics |
client.tenants | Tenant Settings | Manage tenant-level configuration |
client.tickets | Tickets | Generate email verification and password change tickets |
client.users | Users | Manage user accounts |
Each sub-client implements standard CRUD operations (list, create, get, update, delete) with resource-specific variations.
Sources: README.md69-157 CHANGELOG.md12
The SDK provides parallel synchronous and asynchronous client implementations:
| API | Synchronous Classes | Asynchronous Classes | HTTP Library |
|---|---|---|---|
| Authentication | GetToken, Auth0, Database, TokenVerifier | AsyncAuth0, AsyncTokenVerifier | requests (sync), aiohttp (async) |
| Management v5 | ManagementClient, Auth0 | AsyncManagementClient, AsyncAuth0 | httpx (unified sync/async) |
Key differences in v5.0:
requests for sync, aiohttp for async) for backward compatibilityhttpx exclusively, which provides unified sync/async support through a single HTTP client library*_async suffix (e.g., get_async()), while Management v5 async clients use native async def methodsSources: README.md91-107 README.md158-185 CHANGELOG.md21
Diagram 3: HTTP Client Architecture
The Authentication API uses separate HTTP libraries for sync (requests) and async (aiohttp), while Management API v5 uses httpx for both execution modes. This separation maintains backward compatibility for Authentication while modernizing the Management API.
Sources: README.md48-66 README.md309-321
Diagram 4: Exception Architecture
Version 5.0 introduced separate exception hierarchies:
Auth0Error (base), RateLimitError (429 responses), and TokenValidationError (JWT validation)ApiError for all HTTP errorsImport paths differ: from auth0.exceptions import Auth0Error vs from auth0.management.core.api_error import ApiError
Sources: README.md187-200 CHANGELOG.md15
The v5.0 release introduced significant breaking changes in the Management API:
| Change Category | v4.x | v5.0 |
|---|---|---|
| Client Initialization | Auth0(domain='x.auth0.com', token='...', ...) | ManagementClient(domain='x.auth0.com', token='...') or Auth0(base_url='https://x.auth0.com/api/v2', token='...') |
| Method Organization | Flat methods on endpoint classes | Modular sub-clients with resource-specific methods |
| Response Types | Generic dictionaries | Pydantic models with type validation |
| Error Handling | from auth0.exceptions import Auth0Error | from auth0.management.core.api_error import ApiError |
| HTTP Client | requests (sync), aiohttp (async) | httpx (unified) |
| Pagination Defaults | include_totals=False | include_totals=True |
| Python Support | 3.7+ (4.x), 3.8+ (5.0) | 3.8+ (3.7 dropped) |
Important: The Authentication API remains fully backward compatible. No changes required for authentication code.
Sources: CHANGELOG.md3-40 README.md33
The SDK uses poetry-dynamic-versioning for git-tag-based version derivation:
| SDK Version | Python Versions | Notes |
|---|---|---|
| 5.0.0b0 (beta) | 3.8, 3.9, 3.10, 3.11, 3.12 | Python 3.7 support dropped |
| 4.x | 3.8, 3.9, 3.10, 3.11, 3.12 | Current stable |
| 4.7.0 | 3.8-3.12 | First version to drop 3.7 |
| 4.6.1 | 3.7-3.11 | Last version supporting 3.7 |
See Page 1.3 for detailed version history and Page 1.2 for migration guidance.
Sources: CHANGELOG.md3-6 CHANGELOG.md117-119 README.md41-43
Version 5.0 introduced separate dependency sets for each API:
| Dependency | Version | Used By | Purpose |
|---|---|---|---|
| Authentication API Dependencies | |||
requests | >= 2.32.3 | auth0.authentication (sync) | Synchronous HTTP client |
aiohttp | >= 3.10.11 | auth0.authentication (async) | Asynchronous HTTP client |
pyjwt | >= 2.8.0 | TokenVerifier, AsyncTokenVerifier | JWT encoding/decoding |
cryptography | >= 43.0.1 | JWT signature verification | RSA/HMAC cryptographic operations |
| Management API v5 Dependencies | |||
httpx | >= 0.21.2 | auth0.management | Modern async/sync HTTP client |
pydantic | >= 1.9.2 | All Management v5 models | Type-safe request/response models |
pydantic-core | >= 2.18.2 | Pydantic runtime | Pydantic validation engine |
typing_extensions | >= 4.0.0 | Type hints | Backport of Python 3.10+ typing features |
The dependency split reflects the architectural divergence: Authentication maintains backward compatibility with its original dependencies, while Management v5 uses modern libraries for type safety and unified sync/async support.
Sources: CHANGELOG.md3-40 README.md41-43
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
This wiki was recently refreshed. Please wait 4 days to refresh again.