Skip to content

Commit f7bf81b

Browse files
darrickyongdarrickyong
authored
feat: replicate mgmt-api index (#764)
* feat: replicate content into mgmt-api index.mdx * fix: add description to en-myaccount index.mdx * feat: copy placeholder eng mgmt-api content to fr-ca and ja-jp * feat: copy placeholder eng myaccount content to fr-ca and ja-jp
1 parent 6a56b1c commit f7bf81b

6 files changed

Lines changed: 668 additions & 2 deletions

File tree

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: "Management API Reference"
3+
description: "Documentation for Auth0's Management API"
4+
---
5+
6+
<Badge>Version: 2.0 (Current)</Badge>
7+
8+
**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.
9+
10+
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.
11+
12+
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.
13+
14+
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.
15+
16+
## Authentication
17+
18+
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).
19+
20+
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.
21+
22+
```bash lines
23+
{
24+
"aud": "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
25+
"scopes": {
26+
"connections": {
27+
"actions": ["read", "update"]
28+
}
29+
},
30+
"iat": "1446056652",
31+
"jti": "7e9c6a991f5a227fb7ebaa522536ae4c"
32+
}
33+
```
34+
35+
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).
36+
37+
```bash lines
38+
curl -H "Authorization: Bearer eyJhb..." https://@@TENANT@@/api/v2/users
39+
```
40+
41+
## Request Correlation
42+
43+
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).
44+
45+
The API accepts a client-provided Correlation ID if sent with the `X-Correlation-ID` HTTP header within `POST`, `PUT`, `PATCH`, and `DELETE` methods.
46+
47+
```bash lines
48+
curl -H "Authorization: Bearer eyJhb..." -H "x-correlation-id: client1_xyz" https://@@TENANT@@/api/v2/users
49+
```
50+
51+
If an `X-Correlation-ID` header value longer than 64 characters is provided, only the first 64 characters will be shown in the logs.
52+
53+
```bash lines
54+
"references": {
55+
"correlation_id": "client1_xyz"
56+
}
57+
```
58+
59+
## Pagination
60+
61+
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.
62+
63+
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.
64+
65+
### Offset-Based Pagination
66+
67+
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.
68+
69+
- **Parameters:**
70+
- `page`: The zero-indexed page number to retrieve. Defaults to `0` if not specified.
71+
- `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.
72+
73+
**Example Offset-Based Pagination Request:**
74+
75+
```bash lines
76+
curl -L "https://@@TENANT@@/api/v2/clients?per_page=10&page=2" \
77+
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
78+
-H 'Accept: application/json'
79+
```
80+
81+
In offset pagination:
82+
83+
- If `page * per_page` exceeds the total number of results, an empty array is returned.
84+
- 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.
85+
86+
### Checkpoint-Based Pagination
87+
88+
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.
89+
90+
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.
91+
92+
- **Parameters:**
93+
- `from`: The next checkpoint ID from the previous response, used to retrieve the next page of results.
94+
- `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.
95+
96+
**Example Checkpoint-Based Pagination Request:**
97+
98+
```bash lines
99+
curl -L "https://@@TENANT@@/api/v2/clients?take=10&from=Cg1HRUY3NEszUERFME40GgAiAQgCEj..." \
100+
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
101+
-H 'Accept: application/json'
102+
```
103+
104+
#### Checkpoint ID Expiry
105+
106+
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.
107+
108+
<Note>
109+
<p class="uppercase font-bold">Note</p>
110+
111+
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.
112+
113+
</Note>
114+
115+
#### Forward-Only Constraints
116+
117+
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.
118+
119+
### Choosing Between Offset and Checkpoint Pagination
120+
121+
When both pagination types are supported:
122+
123+
- **Use checkpoint-based pagination** for handling large datasets efficiently.
124+
- Use offset-based pagination for smaller datasets (typically under 1,000 items), as it is simpler to implement but less efficient for large collections.
125+
126+
### Best Practices for Handling Pagination
127+
128+
- **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.
129+
- **Checkpoint Storage:** For large data retrieval, consider storing checkpoints after each page to allow resumption from the last checkpoint if interrupted.
130+
131+
This approach provides efficient and stable data retrieval for large datasets, aligned with the Auth0 Management API’s pagination options.

‎main/docs/api/myaccount/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: "My Account API Reference"
3+
description: "Documentation for Auth0's My Account API"
34
---
45

56
<Badge>Version: 1.0 (Current)</Badge>

‎main/docs/fr-ca/api/management/v2/index.mdx‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: "Management API Reference"
3+
description: "Documentation for Auth0's Management API"
4+
---
5+
6+
<Badge>Version: 2.0 (Current)</Badge>
7+
8+
**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.
9+
10+
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.
11+
12+
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.
13+
14+
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.
15+
16+
## Authentication
17+
18+
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).
19+
20+
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.
21+
22+
```bash lines
23+
{
24+
"aud": "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
25+
"scopes": {
26+
"connections": {
27+
"actions": ["read", "update"]
28+
}
29+
},
30+
"iat": "1446056652",
31+
"jti": "7e9c6a991f5a227fb7ebaa522536ae4c"
32+
}
33+
```
34+
35+
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).
36+
37+
```bash lines
38+
curl -H "Authorization: Bearer eyJhb..." https://@@TENANT@@/api/v2/users
39+
```
40+
41+
## Request Correlation
42+
43+
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).
44+
45+
The API accepts a client-provided Correlation ID if sent with the `X-Correlation-ID` HTTP header within `POST`, `PUT`, `PATCH`, and `DELETE` methods.
46+
47+
```bash lines
48+
curl -H "Authorization: Bearer eyJhb..." -H "x-correlation-id: client1_xyz" https://@@TENANT@@/api/v2/users
49+
```
50+
51+
If an `X-Correlation-ID` header value longer than 64 characters is provided, only the first 64 characters will be shown in the logs.
52+
53+
```bash lines
54+
"references": {
55+
"correlation_id": "client1_xyz"
56+
}
57+
```
58+
59+
## Pagination
60+
61+
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.
62+
63+
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.
64+
65+
### Offset-Based Pagination
66+
67+
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.
68+
69+
- **Parameters:**
70+
- `page`: The zero-indexed page number to retrieve. Defaults to `0` if not specified.
71+
- `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.
72+
73+
**Example Offset-Based Pagination Request:**
74+
75+
```bash lines
76+
curl -L "https://@@TENANT@@/api/v2/clients?per_page=10&page=2" \
77+
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
78+
-H 'Accept: application/json'
79+
```
80+
81+
In offset pagination:
82+
83+
- If `page * per_page` exceeds the total number of results, an empty array is returned.
84+
- 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.
85+
86+
### Checkpoint-Based Pagination
87+
88+
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.
89+
90+
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.
91+
92+
- **Parameters:**
93+
- `from`: The next checkpoint ID from the previous response, used to retrieve the next page of results.
94+
- `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.
95+
96+
**Example Checkpoint-Based Pagination Request:**
97+
98+
```bash lines
99+
curl -L "https://@@TENANT@@/api/v2/clients?take=10&from=Cg1HRUY3NEszUERFME40GgAiAQgCEj..." \
100+
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
101+
-H 'Accept: application/json'
102+
```
103+
104+
#### Checkpoint ID Expiry
105+
106+
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.
107+
108+
<Note>
109+
<p class="uppercase font-bold">Note</p>
110+
111+
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.
112+
113+
</Note>
114+
115+
#### Forward-Only Constraints
116+
117+
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.
118+
119+
### Choosing Between Offset and Checkpoint Pagination
120+
121+
When both pagination types are supported:
122+
123+
- **Use checkpoint-based pagination** for handling large datasets efficiently.
124+
- Use offset-based pagination for smaller datasets (typically under 1,000 items), as it is simpler to implement but less efficient for large collections.
125+
126+
### Best Practices for Handling Pagination
127+
128+
- **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.
129+
- **Checkpoint Storage:** For large data retrieval, consider storing checkpoints after each page to allow resumption from the last checkpoint if interrupted.
130+
131+
This approach provides efficient and stable data retrieval for large datasets, aligned with the Auth0 Management API’s pagination options.

0 commit comments

Comments
 (0)