application/json. All endpoints accept a maximum payload size of 1 megabyte.
The Auth0 Management API documentation follows the Auth0 Management API OpenAPI v3.1 schema. Please note that OpenAPI v3.1 schema support is currently in Beta.
Authentication
Use of the Auth0 Management API requires a Management API access token. To learn how to request this token, read Management API Access Tokens. The Auth0 Management API uses JSON Web Tokens (JWTs) to authenticate requests. The Management API access token’s scopes claim indicates which request methods can be performed when calling this API. The deserialized example token on this page grants read-only access to users and read/write access to connections. Trying to perform any request method not permitted within the set scopes will result in a 403 Forbidden response.Request Correlation
A Correlation ID is a unique identifier (up to 64 characters) of a single Management API operation and allows for tracking such operations in tenant logs. To learn more, read Logs. The API accepts a client-provided Correlation ID if sent with theX-Correlation-ID HTTP header within POST, PUT, PATCH, and DELETE methods.
X-Correlation-ID header value longer than 64 characters is provided, only the first 64 characters will be shown in the logs.
Pagination
Pagination is a technique used by APIs to divide large datasets into manageable pages, reducing the amount of data returned in each response. Two primary types of pagination are common across APIs: offset-based and checkpoint-based pagination. Each has distinct advantages and use cases depending on the dataset size and retrieval requirements. The Auth0 Management API supports both pagination types on many endpoints, such asGET /api/v2/clients and GET /api/v2/logs. When both options are available, checkpoint-based pagination is recommended for its greater efficiency and stability with large datasets.
Offset-Based Pagination
Offset-based pagination is a simple, widely-used method for paginating datasets up to approximately 1,000 items. This approach usespage and per_page parameters to define the starting point and number of items on each page.
- Parameters:
page: The zero-indexed page number to retrieve. Defaults to0if not specified.per_page: The number of items to return per page. For Public Cloud tenants, the maximum is50; for Private Cloud, the maximum is100. If not specified, defaults to half the maximum.
- If
page * per_pageexceeds the total number of results, an empty array is returned. - Each page request recalculates the offset, which can impact performance with larger datasets. Offset pagination is generally better suited for collections that are unlikely to exceed 1,000 items.
Checkpoint-Based Pagination
Checkpoint-based pagination, also known as cursor-based or token-based pagination, is optimized for large datasets. This method uses anext checkpoint ID provided by the server to retrieve subsequent pages in a forward-only sequence. The next checkpoint ID is included in the response when additional results are available.
To continue pagination, use the next checkpoint ID in the from query parameter of the subsequent request. This ID is opaque and should be passed without modification.
- Parameters:
from: The next checkpoint ID from the previous response, used to retrieve the next page of results.take: The number of items to return per page. For Public Cloud tenants, the maximum is50; for Private Cloud, the maximum is100. Defaults to half the maximum if not provided.
Checkpoint ID Expiry
When using checkpoint-based pagination, it’s important to be aware of the lifespan of eachnext checkpoint ID. The checkpoint ID is designed to be used in a sequential manner, with each ID valid for a limited duration to ensure data consistency.
Note
Thenext checkpoint ID is valid for 24 hours from issuance. If it expires, a fresh request is required to restart from the beginning of the dataset. Consider caching results if extended time may elapse between requests.Forward-Only Constraints
Checkpoint-based pagination is forward-only. Avoid using the checkpoint ID for backward navigation or out-of-sequence requests, as this may lead to errors. Always use thenext checkpoint ID from the previous response.
Choosing Between Offset and Checkpoint Pagination
When both pagination types are supported:- Use checkpoint-based pagination for handling large datasets efficiently.
- Use offset-based pagination for smaller datasets (typically under 1,000 items), as it is simpler to implement but less efficient for large collections.
Best Practices for Handling Pagination
- Data Consistency: Each paginated request reflects the data at the time of the request. If data is updated or deleted, there may be skipped or repeated items. Checkpoint-based pagination can help maintain smoother pagination in dynamic datasets.
- Checkpoint Storage: For large data retrieval, consider storing checkpoints after each page to allow resumption from the last checkpoint if interrupted.