Management API

Relevant source files

• CHANGELOG.md
• README.md

The Management API client provides programmatic access to the Auth0 Management API v2, enabling automation of tenant configuration, user management, and administrative operations. Version 5.0 introduced a complete rewrite of the Management API client, generated from Auth0's OpenAPI specifications using Fern.

For information about user authentication flows and token acquisition, see Authentication API. For details on the underlying HTTP infrastructure, see HTTP Infrastructure.

---

Version 5.0 Rewrite

The v5.0 release represents a fundamental architectural change to the Management API client:

Key Changes:

• Complete code generation from OpenAPI specifications using Fern
• Modular sub-client architecture replacing flat method structure
• Type-safe request/response objects using Pydantic models
• Automatic token management with client credentials
• First-class async support with dedicated async clients
• Simplified initialization using domain instead of full base_url
• New ApiError exception hierarchy replacing legacy Auth0Error

Backward Compatibility: The Authentication API remains fully backward compatible. Only the Management API client underwent breaking changes.

Sources: CHANGELOG.md3-39 README.md33-39

---

Client Hierarchy

Version 5.0 introduces two levels of abstraction for Management API access:

Diagram: Management Client Hierarchy

Sources: README.md68-157 CHANGELOG.md10-27

---

Recommended Client: ManagementClient

The ManagementClient is the recommended way to interact with the Management API. It provides automatic token management and simplified initialization.

Initialization with Automatic Token Management

Initialization with Existing Token

Key Features:

• Accepts domain parameter (e.g., "your-tenant.auth0.com") instead of full base_url
• Automatically acquires Management API token when initialized with client_id and client_secret
• Handles token refresh transparently
• Exposes 20+ modular sub-clients for different resource types

Sources: README.md68-89 CHANGELOG.md17

---

Base Client: Auth0

The Auth0 base client provides manual token management and requires a full base_url. It offers lower-level control for advanced use cases.

Initialization

Use Case: Integration with Authentication API

When to Use Base Client:

• You need manual control over token lifecycle
• You're integrating with existing token acquisition logic
• You're managing multiple tokens with different scopes
• You prefer explicit URL construction

Sources: README.md109-157

---

Async Support

Both ManagementClient and Auth0 have async counterparts for non-blocking operations.

AsyncManagementClient

AsyncAuth0

Note: When constructing a custom httpx client for async usage, use httpx.AsyncClient() instead of httpx.Client().

For detailed async patterns and examples, see Asynchronous Support.

Sources: README.md91-185

---

Modular Sub-Client Architecture

Version 5.0 restructures the Management API into modular sub-clients, each representing a specific resource type. This provides better code organization and improved discoverability.

Diagram: Sub-Client Access Pattern

Usage Pattern

Available Sub-Clients: The Management API provides 20+ sub-clients for different resource types including:

• users - User management
• organizations - Organization management
• actions - Auth0 Actions (extensibility)
• roles - Role-based access control
• clients - Application management
• connections - Authentication connections
• branding - Tenant branding
• Additional clients documented in Resource Management

For detailed sub-client structure and architecture, see Sub-Client Architecture (v5).

Sources: CHANGELOG.md12 README.md74-108

---

Type Safety with Pydantic

Version 5.0 introduces strongly-typed request and response objects using Pydantic models, replacing generic dictionaries.

Benefits

Compile-Time Validation:

• IDE autocomplete and IntelliSense support
• Type checking with mypy
• Reduced runtime errors

Runtime Validation:

• Automatic validation of request payloads
• Type coercion for compatible types
• Detailed error messages for invalid data

Self-Documenting:

• Clear data structures in code
• Embedded field documentation
• Easier maintenance and refactoring

Example Usage

Sources: CHANGELOG.md14 CHANGELOG.md24

---

Error Handling

Version 5.0 introduces a new exception hierarchy with the ApiError base class, replacing the legacy Auth0Error.

ApiError Exception

Error Response Structure

When the API returns a non-success status code (4xx or 5xx), an ApiError is raised with:

• status_code - HTTP status code (e.g., 400, 401, 429, 500)
• body - Parsed response body containing error details
• Standard Python exception attributes

Common Error Codes:

• 400 - Bad Request (validation errors)
• 401 - Unauthorized (invalid or expired token)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found (resource doesn't exist)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Sources: README.md187-201 CHANGELOG.md15

---

Pagination

Version 5.0 provides built-in pagination support with SyncPager and AsyncPager objects that automatically handle page fetching.

Item-Level Iteration

Page-Level Iteration

Default Behavior

Version 5.0 changes pagination defaults:

• include_totals=True is now the default for list operations
• First page is automatically fetched and cached
• Subsequent pages are fetched on-demand as iteration progresses

For detailed pagination patterns, see Pagination.

Sources: README.md203-236 CHANGELOG.md16 CHANGELOG.md23

---

Advanced Configuration

The Management API client supports advanced customization through request options and custom HTTP clients.

Custom Timeouts

Custom Retries

Default Retry Behavior:

• Maximum 2 retries by default
• Retries on HTTP 408 (Timeout), 429 (Too Many Requests), and 5xx errors
• Exponential backoff between retries

Custom HTTP Client

For detailed HTTP configuration options, see HTTP Client Configuration.

Sources: README.md284-321

---

Usage Example

Basic Management Operations

Advanced Configuration

Sources: README.md54-82 auth0/management/auth0.py42-58

---

Async Support

The Management SDK supports asynchronous operations through the AsyncAuth0 class. For complete details, see Asynchronous Support.

Sources: auth0/management/__init__.py34-37