Management API リファレンス

Auth0 の Management API に関するドキュメント

バージョン: 2.0 (Current)

Auth0 Management API は、管理タスクをプログラムから実行するためのエンドポイント群で、バックエンドサーバーまたは信頼できる主体が使用することを想定しています。一般的に、Auth0 Dashboard で実行できることは、この API でも実行できます。

この API は、フロントエンドや信頼できない主体による利用を想定した 一般公開された Auth0 Authentication API とは別のものです。

この API ドキュメントに含まれるコードサンプルを使用する場合、request は Content-Type を application/json にして送信する必要があります。すべての endpoint で、最大 1 メガバイトの payload を受け付けます。

Auth0 Management API のドキュメントは、Auth0 Management API OpenAPI v3.1 schema に準拠しています。なお、OpenAPI v3.1 schema のサポートは現在ベータ版です。

​

認証

Auth0 Management API を使用するには、Management API アクセストークンが必要です。このトークンの取得方法については、Management API Access Tokensを参照してください。

Auth0 Management API では、リクエストの認証に JSON Web Tokens (JWT) を使用します。Management API アクセストークンの scopes クレームは、この API の呼び出し時に使用できるリクエストメソッドを示します。このページのデシリアライズされたトークン例では、ユーザーに対する読み取り専用アクセスと、接続に対する読み取り/書き込みアクセスが許可されています。設定された scopes で許可されていないリクエストメソッドを実行しようとすると、403 Forbidden 応答が返されます。

{
  "aud": "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
  "scopes": {
    "connections": {
      "actions": ["read", "update"]
    }
  },
  "iat": "1446056652",
  "jti": "7e9c6a991f5a227fb7ebaa522536ae4c"
}

APIを呼び出すには、Bearer 認証方式を使用し、Authorization HTTP ヘッダーで API トークンを送信します。

curl -H "Authorization: Bearer eyJhb..." https://@@TENANT@@/api/v2/users

​

リクエストの関連付け

Correlation ID は、1 回の Management API 操作に対して付与される一意の識別子 (最大 64 文字) で、テナントのログでその操作を追跡できるようにするものです。詳しくは、ログを参照してください。

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 Access Tokens を取得するをご覧ください。