Merge remote-tracking branch 'origin/main' into feat/mintlify-components-integration-staging

Author: grandmaester

main/docs.json

@@ -0,0 +1,131 @@
+---
+title: "Management API Reference"
+description: "Documentation for Auth0's Management API"
+---
+
+<Badge>Version: 2.0 (Current)</Badge>
+
+**The Auth0 Management API** is a collection of endpoints to complete administrative tasks programmatically and should be used by back-end servers or trusted parties. Generally speaking, anything that can be done through the Auth0 Dashboard can also be done through this API.
+
+This API is separate from the [publicly accessible Auth0 Authentication API](https://auth0.com/docs/api/authentication), which is meant to be used by front-ends and untrusted parties.
+
+When using the code samples included in this API documentation, requests should be sent with a Content-Type of `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](https://auth0.com/docs/api/management/openapi.json). 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](https://auth0.com/docs/secure/tokens/access-tokens/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.
+
+```bash lines
+{
+  "aud": "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
+  "scopes": {
+    "connections": {
+      "actions": ["read", "update"]
+    }
+  },
+  "iat": "1446056652",
+  "jti": "7e9c6a991f5a227fb7ebaa522536ae4c"
+}
+```
+
+To make calls to the API, send the API token in the Authorization HTTP header using the [Bearer authentication scheme](https://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-20#section-2.1).
+
+```bash lines
+curl -H "Authorization: Bearer eyJhb..." https://@@TENANT@@/api/v2/users
+```
+
+## 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](https://auth0.com/docs/deploy-monitor/logs).
+
+The API accepts a client-provided Correlation ID if sent with the `X-Correlation-ID` HTTP header within `POST`, `PUT`, `PATCH`, and `DELETE` methods.
+
+```bash lines
+curl -H "Authorization: Bearer eyJhb..." -H "x-correlation-id: client1_xyz" https://@@TENANT@@/api/v2/users
+```
+
+If an `X-Correlation-ID` header value longer than 64 characters is provided, only the first 64 characters will be shown in the logs.
+
+```bash lines
+"references": {
+  "correlation_id": "client1_xyz"
+}
+```
+
+## 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 as `GET /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 uses `page` 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 to `0` if not specified.
+  - `per_page`: The number of items to return per page. For Public Cloud tenants, [the maximum is `50`](https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-paginated-queries); for Private Cloud, the maximum is `100`. If not specified, defaults to half the maximum.
+
+**Example Offset-Based Pagination Request:**
+
+```bash lines
+curl -L "https://@@TENANT@@/api/v2/clients?per_page=10&page=2" \
+-H 'Authorization: Bearer {ACCESS_TOKEN}' \
+-H 'Accept: application/json'
+```
+
+In offset pagination:
+
+- If `page * per_page` exceeds 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 a `next` 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 is `50`](https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-paginated-queries); for Private Cloud, the maximum is `100`. Defaults to half the maximum if not provided.
+
+**Example Checkpoint-Based Pagination Request:**
+
+```bash lines
+curl -L "https://@@TENANT@@/api/v2/clients?take=10&from=Cg1HRUY3NEszUERFME40GgAiAQgCEj..." \
+-H 'Authorization: Bearer {ACCESS_TOKEN}' \
+-H 'Accept: application/json'
+```
+
+#### Checkpoint ID Expiry
+
+When using checkpoint-based pagination, it’s important to be aware of the lifespan of each `next` 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>
+  <p class="uppercase font-bold">Note</p>
+
+The `next` 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.
+
+</Note>
+
+#### 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 the `next` 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.
+
+This approach provides efficient and stable data retrieval for large datasets, aligned with the Auth0 Management API’s pagination options.

main/docs/api/management/v2/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: "My Account API Reference"
+description: "Documentation for Auth0's My Account API"
 ---
 
 <Badge>Version: 1.0 (Current)</Badge>

main/docs/api/myaccount/index.mdx

@@ -3,6 +3,11 @@ openapi: myorganization-api-oas get /config
 playground: simple
 ---
 
+{/*
+OAS version: 1.8690.0
+Snippet version: 0.0.4
+*/}
+
 import { ApiReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
 import { Scopes } from "/snippets/ApiScopes.jsx";
 

main/docs/api/myorganization/config/get-configuration.mdx

@@ -3,6 +3,11 @@ openapi: myorganization-api-oas get /config/identity-providers
 playground: simple
 ---
 
+{/*
+OAS version: 1.8690.0
+Snippet version: 0.0.4
+*/}
+
 import { ApiReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
 import { Scopes } from "/snippets/ApiScopes.jsx";
 

main/docs/api/myorganization/config/get-identity-providers-configuration.mdx

@@ -3,6 +3,11 @@ openapi: myorganization-api-oas post /identity-providers/{idp_id}/domains
 playground: simple
 ---
 
+{/*
+OAS version: 1.8690.0
+Snippet version: 0.0.4
+*/}
+
 import { ApiReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
 import { Scopes } from "/snippets/ApiScopes.jsx";
 

main/docs/api/myorganization/idp-management/associate-domain-with-identity-provider.mdx

@@ -3,6 +3,11 @@ openapi: myorganization-api-oas post /identity-providers
 playground: simple
 ---
 
+{/*
+OAS version: 1.8690.0
+Snippet version: 0.0.4
+*/}
+
 import { ApiReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
 import { Scopes } from "/snippets/ApiScopes.jsx";
 

main/docs/api/myorganization/idp-management/create-identity-provider.mdx

@@ -3,6 +3,11 @@ openapi: myorganization-api-oas post /identity-providers/{idp_id}/provisioning
 playground: simple
 ---
 
+{/*
+OAS version: 1.8690.0
+Snippet version: 0.0.4
+*/}
+
 import { ApiReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
 import { Scopes } from "/snippets/ApiScopes.jsx";
 

main/docs/api/myorganization/idp-management/create-provisioning-configuration.mdx

@@ -3,6 +3,11 @@ openapi: myorganization-api-oas post /identity-providers/{idp_id}/provisioning/s
 playground: simple
 ---
 
+{/*
+OAS version: 1.8690.0
+Snippet version: 0.0.4
+*/}
+
 import { ApiReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
 import { Scopes } from "/snippets/ApiScopes.jsx";
 

main/docs/api/myorganization/idp-management/create-provisioning-scim-token.mdx

@@ -3,6 +3,11 @@ openapi: myorganization-api-oas delete /identity-providers/{idp_id}
 playground: simple
 ---
 
+{/*
+OAS version: 1.8690.0
+Snippet version: 0.0.4
+*/}
+
 import { ApiReleaseLifecycle } from "/snippets/ApiReleaseLifecycle.jsx";
 import { Scopes } from "/snippets/ApiScopes.jsx";