This document covers the Auth0 Python SDK's Authentication API client, which provides programmatic access to Auth0's Authentication API endpoints for implementing OAuth 2.0 and OpenID Connect authentication flows. The Authentication API is used to obtain, verify, and manage tokens for user authentication and authorization.
For detailed information about specific authentication flows (client credentials, authorization code, PKCE, passwordless, CIBA), see Token Acquisition (OAuth 2.0 Flows). For token verification and validation, see Token Verification. For advanced features like PAR, JAR, and RAR, see Advanced Authentication Flows.
For Management API operations (user management, client configuration, etc.), see Management API.
Note: The Authentication API remained fully backward compatible during the v5.0.0 rewrite. All v4.x Authentication API code continues to work without modifications in v5.x.
The Authentication API client is organized around token lifecycle operations and implements standard OAuth 2.0 and OpenID Connect specifications.
Sources: README.md43-61 CHANGELOG.md91-96 requirements.txt7-12
The GetToken class is the primary entry point for Authentication API operations. It handles token acquisition across all supported OAuth 2.0 flows.
Sources: README.md43-61 pyproject.toml44-49
The GetToken client requires three core parameters: domain, client_id, and client_secret.
Synchronous Client:
Asynchronous Client:
Sources: README.md45-60
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Auth0 tenant domain (e.g., "tenant.auth0.com") |
client_id | string | Yes | Application client ID |
client_secret | string | Yes* | Application client secret (*not required for public clients using PKCE) |
client_assertion | string | No | JWT assertion for private_key_jwt authentication method |
client_assertion_type | string | No | URN identifier for JWT bearer assertion type |
Sources: CHANGELOG.md210
The Authentication API client provides three major capability areas:
The GetToken client implements multiple OAuth 2.0 grant types:
For detailed documentation on each flow, including parameters and examples, see Token Acquisition (OAuth 2.0 Flows).
Sources: CHANGELOG.md542-548 README.md45-60
Token lifecycle operations:
Example:
Sources: CHANGELOG.md530 CHANGELOG.md461
The SDK provides robust token verification capabilities with OIDC compliance:
For comprehensive token verification documentation, see Token Verification.
Sources: CHANGELOG.md380 CHANGELOG.md189
PAR improves security by sending authorization parameters via a direct back-channel request rather than through the browser. Added in v4.7.0.
Sources: CHANGELOG.md127
JAR enables passing authorization parameters as a signed JWT for enhanced integrity and confidentiality. Added in v4.8.0.
Sources: CHANGELOG.md95
RAR provides fine-grained authorization by allowing detailed authorization requirements in the authorization request. Added in v4.9.0.
Sources: CHANGELOG.md83
For detailed documentation on PAR, JAR, and RAR, see Advanced Authentication Flows.
The Authentication API uses a distinct dependency stack optimized for token operations and cryptographic functions:
Key Dependencies:
| Dependency | Version | Purpose |
|---|---|---|
requests | >=2.32.3 | Synchronous HTTP client for token requests |
aiohttp | >=3.10.11 | Asynchronous HTTP client for async operations |
pyjwt | >=2.8.0 | JWT encoding, decoding, and validation |
cryptography | >=43.0.1 | Cryptographic operations (RSA, ECDSA) |
urllib3 | >=2.2.3 | HTTP connection pooling and management |
Sources: requirements.txt7-12 pyproject.toml44-49
The Authentication API supports both synchronous and asynchronous operations using the same client interface:
Synchronous calls use the requests library and block until the response is received:
Asynchronous calls use aiohttp and must be awaited within an async context:
Async Session Sharing:
For applications making multiple Authentication API calls, shared sessions improve performance by reusing HTTP connections:
Sources: CHANGELOG.md235-236 CHANGELOG.md252
The SDK has evolved to support modern authentication methods:
Sources: CHANGELOG.md210 CHANGELOG.md127 CHANGELOG.md95 CHANGELOG.md83
Authentication API errors follow standard HTTP error conventions. Unlike the Management API which uses ApiError in v5.0.0, the Authentication API maintains its own error handling:
Common Error Scenarios:
| HTTP Status | Meaning | Common Causes |
|---|---|---|
| 401 | Unauthorized | Invalid client credentials, expired token |
| 403 | Forbidden | Insufficient permissions, invalid grant type |
| 429 | Too Many Requests | Rate limit exceeded |
| 400 | Bad Request | Invalid parameters, malformed request |
Sources: README.md182-195
The Authentication API and Management API serve different purposes and can be used together:
Typical Pattern:
audience="https://tenant.auth0.com/api/v2/"Sources: README.md104-130
| SDK Version | Python Version | Authentication API Status |
|---|---|---|
| v3.x | Python 3.7+ | Stable |
| v4.x | Python 3.7+ (3.12 from v4.7.0) | Stable, enhanced features (PAR, CIBA) |
| v5.x | Python 3.8+ | Fully backward compatible with v4.x |
Important: The v5.0.0 rewrite only affected the Management API. All Authentication API code from v4.x continues to work without modification in v5.x.
Sources: CHANGELOG.md12-45 CHANGELOG.md120-124 pyproject.toml39
Refresh this wiki