The HTTP infrastructure in auth0-python SDK uses different HTTP libraries depending on the API being accessed, reflecting the architectural split between the v5 Management API and the backward-compatible Authentication API.
HTTP Library Dependencies:
| API | Sync Library | Async Library | Use Case |
|---|---|---|---|
| Management API v5 | httpx | httpx | Fern-generated clients with unified sync/async support |
| Authentication API | requests | aiohttp | Legacy clients maintaining backward compatibility |
This dual-library approach allows the Management API to leverage modern httpx features (unified sync/async, HTTP/2 support, custom transports) while the Authentication API maintains compatibility with existing codebases using requests/aiohttp.
Related Pages:
Sources: requirements.txt1-12 README.md38-43
The SDK's HTTP infrastructure is divided into two distinct implementations:
HTTP Infrastructure Split:
Key Architectural Decisions:
| Decision | Rationale |
|---|---|
| httpx for Management API v5 | Unified sync/async support, HTTP/2, modern request/response model, custom transports |
| requests for Authentication API (sync) | Widespread adoption, stable API, maintains backward compatibility |
| aiohttp for Authentication API (async) | Mature async HTTP client, existing SDK patterns |
The Management API's httpx integration enables advanced configuration patterns documented in HTTP Client Configuration, while the Authentication API maintains legacy patterns for existing users.
Sources: requirements.txt1-12 pyproject.toml38-49 </old_str> <new_str>
The HTTP infrastructure in auth0-python SDK uses different HTTP libraries depending on the API being accessed, reflecting the architectural split between the v5 Management API and the backward-compatible Authentication API.
HTTP Library Dependencies:
| API | Sync Library | Async Library | Use Case |
|---|---|---|---|
| Management API v5 | httpx | httpx | Fern-generated clients with unified sync/async support |
| Authentication API | requests | aiohttp | Legacy clients maintaining backward compatibility |
This dual-library approach allows the Management API to leverage modern httpx features (unified sync/async, HTTP/2 support, custom transports) while the Authentication API maintains compatibility with existing codebases using requests/aiohttp.
Related Pages:
Sources: requirements.txt1-12 README.md38-43
The SDK's HTTP infrastructure is divided into two distinct implementations:
HTTP Infrastructure Split:
Key Architectural Decisions:
| Decision | Rationale |
|---|---|
| httpx for Management API v5 | Unified sync/async support, HTTP/2, modern request/response model, custom transports |
| requests for Authentication API (sync) | Widespread adoption, stable API, maintains backward compatibility |
| aiohttp for Authentication API (async) | Mature async HTTP client, existing SDK patterns |
The Management API's httpx integration enables advanced configuration patterns documented in HTTP Client Configuration, while the Authentication API maintains legacy patterns for existing users.
Sources: requirements.txt1-12 pyproject.toml38-49
The SDK employs distinct HTTP client strategies based on the API being accessed, reflecting the v5 architectural redesign:
HTTP Client Architecture:
Key Design Principles:
| Principle | Implementation | Rationale |
|---|---|---|
| Library Unification | httpx for all Management API operations | Consistent sync/async API, single dependency |
| Backward Compatibility | Separate requests/aiohttp for Authentication API | Maintains v4 behavior, avoids breaking changes |
| Code Generation | Fern generates Management API clients | Type safety, automatic API updates, reduced maintenance |
| Configuration Flexibility | Custom httpx client injection | Proxy support, custom transports, advanced scenarios |
Sources: requirements.txt1-12 README.md64-102 pyproject.toml38-49
The v5 rewrite fundamentally changed the HTTP infrastructure for the Management API while preserving the Authentication API's existing implementation. This allows new Management API features to leverage modern HTTP capabilities while maintaining backward compatibility for authentication flows.
Sources: README.md1-102 requirements.txt1-12
The v5 Management API uses httpx as its exclusive HTTP client library, supporting both synchronous and asynchronous operations through a single, unified interface.
httpx Integration Architecture:
httpx Client Injection:
The Management API clients accept custom httpx instances through the httpx_client parameter, enabling advanced configuration:
Available httpx Features:
| Feature | Sync | Async | Configuration Example |
|---|---|---|---|
| HTTP/HTTPS/SOCKS Proxies | ✓ | ✓ | httpx.Client(proxy="http://...") |
| Custom Transports | ✓ | ✓ | httpx.HTTPTransport(retries=3) |
| Connection Pooling | ✓ | ✓ | limits=httpx.Limits(max_connections=100) |
| Request/Response Hooks | ✓ | ✓ | event_hooks={'request': [log_request]} |
| HTTP/2 Support | ✓ | ✓ | httpx.Client(http2=True) |
| Timeout Configuration | ✓ | ✓ | timeout=httpx.Timeout(5.0, read=30.0) |
Why httpx?
The v5 rewrite chose httpx for several architectural reasons:
Detailed configuration patterns are covered in HTTP Client Configuration.
Sources: README.md299-316 requirements.txt1-5 pyproject.toml40
The Authentication API maintains its v4 HTTP infrastructure using separate libraries for synchronous and asynchronous operations, preserving backward compatibility while the Management API underwent its v5 rewrite.
Authentication API HTTP Architecture:
HTTP Library Selection Rationale:
| Library | Version | Key Characteristics | Why This Choice |
|---|---|---|---|
| requests | >=2.32.3 | Synchronous, simple API, widespread adoption | Industry standard for sync HTTP, minimal learning curve |
| aiohttp | >=3.10.11 | Asynchronous, native async/await, client sessions | Mature async HTTP solution, established v3/v4 compatibility |
| urllib3 | >=2.2.3 | Low-level HTTP, connection pooling | requests dependency, provides connection management |
Security-Related Dependencies:
The Authentication API's primary purpose is token operations, requiring specialized cryptographic libraries:
| Dependency | Version | Functionality | Used By |
|---|---|---|---|
| pyjwt | >=2.8.0 | JWT encoding/decoding, signature algorithms | TokenVerifier, GetToken, AsymmetricSignatureVerifier |
| cryptography | >=43.0.1 | RSA/ECDSA key operations, certificate handling | AsymmetricSignatureVerifier, token signing |
Example: Token Acquisition with requests:
Example: Async Authentication with aiohttp:
The Authentication API's decision to maintain requests and aiohttp reflects a conservative approach—avoiding breaking changes for authentication flows while the Management API adopted modern httpx for its v5 rewrite.
Sources: requirements.txt7-12 pyproject.toml44-49 README.md44-61
Despite using different HTTP libraries, both APIs implement similar patterns for common operations like authentication, error handling, and timeout management.
Request Flow Comparison:
Shared Implementation Patterns:
| Pattern | Management API v5 | Authentication API | Implementation Location |
|---|---|---|---|
| Request Authentication | Authorization: Bearer {token} header | Client credentials in request body | Client initialization |
| Response Parsing | Automatic JSON → Pydantic models | Manual JSON → dict | Fern-generated vs. manual |
| Error Handling | ApiError exception hierarchy | Auth0Error exception hierarchy | See Error Handling |
| Rate Limit Retry | Automatic with exponential backoff | Automatic with exponential backoff | See Error Handling |
| Timeout Control | httpx_client parameter or timeout | Constructor timeout parameter | See HTTP Client Configuration |
| Retry Configuration | max_retries in request options | Built-in retry logic | See HTTP Client Configuration |
| Pagination | SyncPager/AsyncPager generators | Not applicable | See Pagination |
Key Differences:
| Aspect | Management API | Authentication API | Reason |
|---|---|---|---|
| Response Type | Pydantic models | Python dicts | Fern generation enables type safety |
| HTTP Library | httpx (unified) | requests + aiohttp (separate) | v5 modernization vs. v4 compatibility |
| Client Lifecycle | Automatic token refresh via client credentials | Manual token acquisition | Management requires ongoing access |
| API Surface | 15+ sub-clients for resources | Single client for auth flows | Management API is resource-oriented |
Example: Timeout Configuration Across APIs:
The pattern divergence reflects the v5 architectural split: Management API clients benefit from httpx's advanced features, while Authentication API clients maintain their proven v4 implementation.
Sources: README.md44-102 README.md279-297
The SDK uses Poetry for dependency management, with runtime dependencies split between Management API and Authentication API concerns.
Dependency Architecture:
Runtime Dependency Breakdown:
| Dependency | Version Constraint | Purpose | Required By |
|---|---|---|---|
| httpx | >=0.21.2 | HTTP client for Management API | ManagementClient, AsyncManagementClient, sub-clients |
| pydantic | >=1.9.2 | Data validation and serialization | All Management API responses |
| pydantic-core | >=2.18.2 | Core Pydantic functionality | Pydantic dependency |
| typing_extensions | >=4.0.0 | Type hints for Python <3.11 | Pydantic, cross-version compatibility |
| requests | >=2.32.3 | HTTP client for sync authentication | GetToken, Database, Social, Passwordless |
| aiohttp | >=3.10.11 | HTTP client for async authentication | AsyncAuth0, async token operations |
| urllib3 | >=2.2.3 | URL utilities and connection pooling | requests dependency |
| pyjwt | >=2.8.0 | JWT encoding/decoding | TokenVerifier, token signing |
| cryptography | >=43.0.1 | Cryptographic primitives | AsymmetricSignatureVerifier, key operations |
Development Dependency Breakdown:
| Dependency | Version Constraint | Purpose |
|---|---|---|
| pytest | ^7.4.0 | Test framework |
| pytest-asyncio | ^0.23.5 | Async test support |
| pytest-xdist | ^3.6.1 | Parallel test execution |
| pytest-aiohttp | ^1.0.4 | aiohttp testing utilities |
| pytest-cov | ^4.1.0 | Code coverage reporting |
| mypy | ==1.13.0 | Static type checking |
| ruff | ==0.11.5 | Linting and code formatting |
| aioresponses | ^0.7.8 | Mock aiohttp responses in tests |
| responses | >=0.23.3,<0.26.0 | Mock requests responses in tests |
| mock | ^5.1.0 | Mocking framework |
| types-requests | ^2.31.0 | Type stubs for requests |
| types-python-dateutil | ^2.9.0.20240316 | Type stubs for dateutil |
Version Constraint Strategy:
| Constraint Type | Example | Meaning | Usage |
|---|---|---|---|
| Minimum version | >=2.32.3 | At least this version | Security patches required |
| Caret constraint | ^7.4.0 | >=7.4.0, <8.0.0 | Dev tools with stable APIs |
| Exact version | ==1.13.0 | Exact match | Tools with breaking changes between minors |
Python Version Compatibility:
The SDK supports Python 3.8+ as declared in pyproject.toml:
This constraint affects dependency resolution:
typing_extensions provides backports for older Python versionsasync-timeout is only required for Python <3.11 (built-in afterward)Build System:
The SDK uses Poetry Core for building, with the poetry-dynamic-versioning plugin for automatic version management from git tags (see Version Management).
mypy Configuration:
The SDK excludes the Authentication API from mypy type checking due to its legacy nature:
Only the Management API v5 (Fern-generated code) undergoes static type analysis, reflecting the architectural split between modern and legacy components.
Sources: requirements.txt1-12 pyproject.toml38-66 pyproject.toml70-74 pyproject.toml99-101
The HTTP infrastructure supports advanced configuration for production use cases.
Configuration Overview:
The Management API supports custom httpx client injection for advanced scenarios:
Supported httpx Features:
| Feature | Description | Example |
|---|---|---|
| Proxy | HTTP/HTTPS/SOCKS proxies | httpx.Client(proxy="http://...") |
| Timeout | Request timeout control | timeout=30.0 or timeout=httpx.Timeout(...) |
| Transport | Custom connection handling | httpx.HTTPTransport(retries=3) |
| HTTP/2 | Enable HTTP/2 protocol | httpx.Client(http2=True) |
For detailed configuration patterns, see HTTP Client Configuration.
Sources: README.md304-321
Both APIs implement structured error handling with exception hierarchies:
Error Handling Comparison:
| API | Exception Base | Key Exceptions | Status Codes |
|---|---|---|---|
| Management API v5 | ApiError | Pydantic-based errors | HTTP 4xx/5xx |
| Authentication API | Auth0Error | RateLimitError, TokenValidationError | HTTP 4xx/5xx |
Error handling details and retry logic are covered in Error Handling and Rate Limiting.
Sources: README.md187-201
Both APIs implement automatic retry logic for 429 (Too Many Requests) responses with exponential backoff:
Rate Limit Handling:
The retry mechanism respects rate limit headers and uses exponential backoff to avoid overwhelming the API. Configuration details are in Error Handling and Rate Limiting.
Sources: README.md264-282
The Management API v5 provides structured pagination support through SyncPager and AsyncPager objects:
Pagination is only available for the Management API. For detailed usage, see Pagination.
Sources: README.md203-236
When enabled, the REST Client includes telemetry information with each request to Auth0. This information helps Auth0 understand how the SDK is being used and aids in troubleshooting.
The telemetry data includes:
This information is Base64-encoded and included in the Auth0-Client header.
Telemetry can be disabled by setting telemetry=False in the RestClientOptions.
Sources: auth0/rest.py95-114 auth0/test/management/test_rest.py793-825
The REST Client automatically handles rate limiting by implementing a retry mechanism with exponential backoff. When a request receives a 429 (Too Many Requests) response, the client will:
The backoff calculation uses the formula:
wait = max(MIN_DELAY, min(MAX_DELAY, (100ms * (2^attempt - 1)) + random(1, MAX_JITTER)))
Where:
MIN_DELAY: 100msMAX_DELAY: 1000msMAX_JITTER: 100msThis approach ensures that:
Sources: auth0/rest.py175-194 auth0/rest.py243-262 auth0/test/management/test_rest.py258-474
The REST Client supports flexible timeout configuration:
Examples:
This flexibility allows for fine-tuning request behavior based on network conditions and API endpoint characteristics.
Sources: auth0/rest.py34-35 auth0/test/management/test_rest.py137-149 auth0/test/management/test_rest.py152-209
Both the Authentication API and Management API components of the SDK use the REST Client for communication with Auth0 APIs. When you create an instance of these components, they internally create and configure a REST Client.
When component methods are called, they use the underlying REST Client to make the appropriate API requests:
Sources: auth0/test/authentication/test_base.py14-43 auth0/authentication/pushed_authorization_requests.py10-35 auth0/test/management/test_branding.py17-138
Refresh this wiki