メインコンテンツへスキップ
バージョン: 2.0 (現行) Auth0 Management API は、管理タスクをプログラムで実行するためのエンドポイント群であり、バックエンドサーバーまたは信頼できるクライアントで使用することを想定しています。一般的に、Auth0 Dashboard で実行できることは、この API でも実行できます。 この API は、フロントエンドや信頼できないクライアントでの使用を想定した 公開されている Auth0 Authentication API とは別のものです。 この API ドキュメントに含まれるコードサンプルを使用する場合、リクエストは Content-Type を application/json にして送信する必要があります。すべてのエンドポイントで受け付けるペイロードの最大サイズは 1 メガバイトです。 Auth0 Management API のドキュメントは、Auth0 Management API OpenAPI v3.1 スキーマ に準拠しています。OpenAPI v3.1 スキーマのサポートは現在ベータ版である点にご注意ください。

​
認証

Auth0 Management API を使用するには、Management API アクセストークンが必要です。このトークンをリクエストする方法については、Management API アクセストークンを参照してください。 Auth0 Management API では、リクエストの認証に JSON Web Token (JWT) を使用します。Management API アクセストークンの scopes クレームは、この API の呼び出し時に実行できるリクエストメソッドを示します。このページのデシリアライズ済みサンプルトークンでは、ユーザーに対する読み取り専用アクセスと、接続に対する読み取り/書き込みアクセスが許可されます。含まれているスコープで許可されていないリクエストメソッドを実行しようとすると、403 Forbidden レスポンスが返されます。 
{
  "aud": "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
  "scopes": {
    "connections": {
      "actions": ["read", "update"]
    }
  },
  "iat": "1446056652",
  "jti": "7e9c6a991f5a227fb7ebaa522536ae4c"
}
API を呼び出すには、Authorization HTTP ヘッダーで Bearer 認証スキーム を使用して API トークンを送信します。 
curl -H "Authorization: Bearer eyJhb..." https://@@TENANT@@/api/v2/users

​
リクエストの相関付け

Correlation ID は、1 回の Management API 操作を一意に識別するための ID (最大 64 文字) であり、テナントログでその操作を追跡できます。詳細については、Logsを参照してください。 API は、POST、PUT、PATCH、DELETE メソッドで X-Correlation-ID HTTP ヘッダーを指定して送信された、クライアント指定の Correlation ID を受け入れます。 
curl -H "Authorization: Bearer eyJhb..." -H "x-correlation-id: client1_xyz" https://@@TENANT@@/api/v2/users
64 文字を超える X-Correlation-ID ヘッダー値が指定された場合、ログには先頭の 64 文字のみが表示されます。 
"references": {
  "correlation_id": "client1_xyz"
}
ページネーションは、API で大規模なデータセットを扱いやすい単位に分割し、各レスポンスで返されるデータ量を抑えるための手法です。API で一般的に使用されるページネーションには、主に オフセットベース と チェックポイントベース の 2 種類があります。どちらにもそれぞれ利点と適したユースケースがあり、データセットの規模や取得要件に応じて使い分けます。 Auth0 Management API は、GET /api/v2/clients や GET /api/v2/logs など、多くのエンドポイントで両方のページネーション方式をサポートしています。両方を利用できる場合は、大規模なデータセットに対する効率と安定性に優れる チェックポイントベースのページネーション を推奨します。

​
オフセットベースのページネーション

オフセットベースのページネーションは、約 1,000 件までのデータセットに対応する、シンプルで広く利用されているページネーション方式です。この方式では、page パラメーターと per_page パラメーターを使用して、開始位置と各ページに含める項目数を指定します。
  • パラメーター:
    • page: 取得する 0 始まりのページ番号です。指定しない場合、デフォルトは 0 です。
    • per_page: 1 ページあたりに返される項目数です。Public Cloud テナントでは、最大値は 50 です。Private Cloud では、最大値は 100 です。指定しない場合、デフォルト値は最大値の半分です。
オフセットベースのページネーションのリクエスト例: 
curl -L "https://@@TENANT@@/api/v2/clients?per_page=10&page=2" \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Accept: application/json'
オフセットベースのページネーションでは:
  • page * per_page が結果の総数を超える場合、空の配列が返されます。
  • 各ページリクエストでオフセットが再計算されるため、データセットが大きい場合はパフォーマンスに影響する可能性があります。一般に、オフセットベースのページネーションは、1,000 件を超える可能性が低いコレクションに適しています。

​
チェックポイントベースのページネーション

チェックポイントベースのページネーションは、カーソルベースまたはトークンベースのページネーションとも呼ばれ、大規模なデータセット向けに最適化されています。この方法では、サーバーから提供される next チェックポイント ID を使用して、後続のページを前方方向にのみ順次取得します。追加の結果がある場合、レスポンスには next チェックポイント ID が含まれます。 ページネーションを続行するには、後続のリクエストの from クエリパラメーターに next チェックポイント ID を指定します。この ID は不透明な値であるため、変更せずにそのまま渡してください。
  • パラメーター:
    • from: 前回のレスポンスで返された次のチェックポイント ID。結果の次のページを取得するために使用します。
    • take: 1 ページあたりに返す項目数。Public Cloud テナントでは、最大値は 50 です。Private Cloud では最大値は 100 です。指定しない場合、既定値は最大値の半分になります。
チェックポイントベースのページネーション リクエストの例: 
curl -L "https://@@TENANT@@/api/v2/clients?take=10&from=Cg1HRUY3NEszUERFME40GgAiAQgCEj..." \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Accept: application/json'

​
チェックポイント ID の有効期限

チェックポイントベースのページネーションを使用する場合は、各 next チェックポイント ID の有効期間を把握しておくことが重要です。チェックポイント ID は順番に使用することを前提として設計されており、データの整合性を確保するため、各 ID は限られた期間のみ有効です。

注記

next チェックポイント ID の有効期間は、発行から 24 時間 です。有効期限が切れた場合は、データセットの先頭から再開するために、新しいリクエストを実行する必要があります。リクエストの間隔が長く空く可能性がある場合は、結果をキャッシュすることを検討してください。

​
順方向のみの制約

チェックポイントベースのページネーションは、前方向にしか進めません。チェックポイント ID を後方への移動や順序どおりでないリクエストに使用しないでください。エラーの原因になる可能性があります。必ず、直前のレスポンスに含まれる next チェックポイント ID を使用してください。

​
オフセットページネーションとチェックポイントページネーションの使い分け

両方のページネーション方式がサポートされている場合:
  • 大規模なデータセットを効率的に処理するには、チェックポイントベースのページネーションを使用します。
  • 小規模なデータセット (通常は 1,000 件未満) には、オフセットベースのページネーションを使用します。こちらは実装が容易ですが、大規模なコレクションでは効率が低下します。

​
ページネーション処理のベストプラクティス

  • データの整合性: 各ページネーションリクエストは、リクエスト時点のデータを反映します。データが更新または削除されると、項目が抜け落ちたり重複したりする場合があります。動的なデータセットでは、チェックポイントベースのページネーションを使用することで、より安定したページネーションを維持できます。
  • チェックポイントの保存: 大量のデータを取得する場合は、各ページの処理後にチェックポイントを保存することを検討してください。これにより、中断が発生しても最後のチェックポイントから再開できます。
このアプローチにより、Auth0 Management API のページネーションオプションに沿って、大規模なデータセットを効率的かつ安定して取得できます。

​
アクセストークンを使用してテストする

テスト用のアクセストークンを取得できます。詳細については、テスト用の Management API アクセストークンを取得するを参照してください。