> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Auth0 API でカスタムスコープを定義および使用して、アクセス制御を実装し、アプリケーション内の権限を適用します。

# API スコープ

API 開発者は、次のことを行う必要があります。

1. アプリケーションがユーザーに代わってアクセスできるようにする情報を決定します。
2. これらのアクセスレベルをカスタムスコープとして定義します。 (スコープについては、[スコープ](/docs/ja-jp/get-started/apis/scopes)を参照してください。)
3. 呼び出し元アプリケーションが利用できるように、これらのスコープを識別します。

<div id="ways-to-use-api-scopes">
  ## API スコープの使い方
</div>

API スコープは、さまざまな形で利用できます。

* 呼び出し元アプリケーションがサードパーティ、つまり外部アプリケーションである API の場合。この場合、呼び出し元アプリケーションは、要求されたスコープへのアクセスについてユーザーに認可を求め、ユーザーはその要求を承認または拒否します。
* 呼び出し元アプリケーションがファーストパーティアプリケーション、つまりその API と同じ Auth0 ドメインの下に登録されているアプリケーションである API の場合。この場合、デフォルトではユーザーの同意は求められませんが、同意を必須にするよう設定することもできます。
* 呼び出し元アプリケーションが、サードパーティかファーストパーティかを問わずバックエンドサービスであり、ユーザーが存在しない API の場合。この場合、ユーザーの同意が求められることはありません。

これらの例はいずれも、トークンを使ってアクセスを制限するためにスコープを利用しています。必要に応じて、API ではトークンに加えて追加のロジックを用い、さらに詳細なアクセス制御を実施することもできます。

アプリケーションのカスタム API アクセスを要求する方法を示す例については、[スコープとクレームのユースケース例](/docs/ja-jp/get-started/apis/scopes/sample-use-cases-scopes-and-claims) を参照してください。

<div id="example-an-api-called-by-a-third-party-application">
  ### 例: サードパーティアプリケーションから呼び出される API
</div>

たとえば、オンライン決済アプリケーションに銀行口座情報を提供する API を構築しているとします。アプリは状況に応じて、口座残高を確認したり、資金を送金したりする必要があります。そのため、この API に 2 つのスコープを作成します。1 つは口座残高の読み取りアクセスを許可するもの (`read:balance`) 、もう 1 つは資金の送金を許可するもの (`transfer:funds`) です。この API は Auth0 に登録されています。

呼び出し元のアプリケーションは、要求するスコープへのアクセスについてユーザーに認可を求め、ユーザーはその要求を承認または拒否します。アプリは、リクエストに `read:balance` スコープを含めることでユーザーの残高を読み取るためのアクセスを要求したり、`transfer:funds` スコープを含めることで資金送金のためのアクセスを要求したり、あるいは `read:balance` と `transfer:funds` の両方のスコープを含めることで、ユーザーの残高の読み取りと資金送金の両方へのアクセスを要求したりできます。

アプリが API を呼び出す際には、ユーザーが自身の情報へのアクセスを認可したことを確認でき、さらにユーザーが承認したスコープも示すトークンが含まれます。API は承認されたスコープを尊重し、ユーザーが呼び出し元のアプリケーションに対して認可した情報だけを返すようにする必要があります。

<div id="example-an-api-called-by-a-first-party-application">
  ### 例: ファーストパーティアプリケーションから呼び出される API
</div>

たとえば、自分で作成したイベントアプリケーションにデータを提供する API を構築しているとします。[ロールベースのアクセス制御 (RBAC) を実装し](/docs/ja-jp/manage-users/access-control/rbac)、`organizer` ロールと `participant` ロールを作成します。`organizer` ロールを持つユーザーにはイベントの作成と更新が必要であり、`participant` ロールを持つユーザーにはイベントの閲覧と登録が必要です。そのため、この API 用に 4 つのスコープを作成します。イベントの作成を認可するスコープ (`create:events`)、イベントの更新を認可するスコープ (`update:events`)、イベントの読み取り専用アクセスを認可するスコープ (`view:events`)、そしてイベントへの登録を認可するスコープ (`register:events`) です。API とイベントアプリケーションはどちらも Auth0 に登録されており、API ではファーストパーティアプリケーション向けの **Allow Skipping User Consent** オプションが有効になっています。Authorization Extension をインストールし、`organizer` ロールを設定して、`create:events` と `update:events` のスコープを作成し、それを User A に割り当てています。また、`participant` ロールも設定し、`view:events` と `register:events` のスコープを作成して、それを User B に割り当てています。

User A はこの呼び出し元アプリケーションで認証され、必要なスコープを要求しますが、ファーストパーティアプリケーションであるため、ユーザーの同意は求められません。アプリは `create:events`、`update:events`、`view:events`、`register:events` の任意の組み合わせのスコープを要求できますが、User A は `organizer` ロールを持つユーザーとして認識されるため、付与されるのは `create:events` と `update:events` のスコープだけです。

その後、アプリが API を呼び出す際には、認証されたユーザーのロールに関連付けられたスコープについてのみ認可されていることを示すトークンが含まれます。

<div id="example-an-api-called-by-a-back-end-service">
  ### 例: バックエンド サービスから呼び出される API
</div>

たとえば、あなたが病院で働いていて、患者が MRI 検査を受けるたびに大量の画像データを生成する API を持っているとします。画像データは 6 か月間ローカルに保存しますが、病院では規制遵守のために、画像を長期保存する必要があります。そのため病院には、毎晩画像データをオフサイトのコールド ストレージ ソリューションにコピーし、ローカルの医療データを保存後 6 か月で削除するサービスがあります。

これを実現するために、API に 2 つのスコープを作成します。1 つは画像データへの読み取りアクセスを許可するもの (`read:images`)、もう 1 つは画像データの削除アクセスを許可するもの (`delete:images`) です。API と自動化サービスは Auth0 に登録されており、自動化サービスが API 用のトークンをリクエストできるよう許可されています。

呼び出し元の自動化サービスは必要なスコープをリクエストしますが、ユーザーが存在しないため、同意は求められません。サービスは、リクエストに `read:images` スコープを含めることで画像データへの読み取りアクセスを、`delete:images` スコープを含めることで削除アクセスを、または `read:images` と `delete:images` の両方のスコープを含めることで、読み取りと削除の両方のアクセスをリクエストできます。

これで、自動化サービスが API を呼び出す際には、要求したスコープに対する認可を持っていることを示すトークンが含まれるようになります。

<div id="limit-api-scopes">
  ## API スコープを制限する
</div>

アプリケーションは、API へのリクエストに、その API で定義されている任意のスコープを含めることができます。ただし、利用可能なすべてのスコープをリクエストできるようにするのではなく、[アプリケーション向け API アクセスポリシー](/docs/ja-jp/get-started/apis/api-access-policies-for-applications) を使用して、アプリケーションの API へのアクセス方法を制御できます。

<div id="learn-more">
  ## 詳しく見る
</div>

* [スコープとクレームのユースケース例](/docs/ja-jp/get-started/apis/scopes/sample-use-cases-scopes-and-claims)
* [API のアクセス許可を追加する](/docs/ja-jp/get-started/apis/add-api-permissions)
* [同意プロンプトをカスタマイズする](/docs/ja-jp/customize/login-pages/customize-consent-prompts)
* [複数の API 向けに論理 API を設定する](/docs/ja-jp/get-started/apis/set-logical-api)
* [本番環境用の Management API アクセストークンを取得する](/docs/ja-jp/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)
* [テスト環境用の Management API アクセストークンを取得する](/docs/ja-jp/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing)