> ## 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.

> スコープの考え方と、API での使用方法を理解します。

# API スコープ

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

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

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

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

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

これらの例はいずれも、トークンを使ってアクセスを制限するためにスコープを使用しています。必要に応じて、API ではトークン以外の追加ロジックを用いて、より高度なアクセス制御を実装することもできます。

アプリケーションにカスタム API アクセスを要求する方法の例については、[Sample Use Cases: Scopes and Claims](/ja/docs/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) ](/ja/docs/manage-users/access-control/rbac)を実装し、`organizer` ロールと `participant` ロールを作成します。`organizer` ロールを持つユーザーはイベントを作成および更新する必要があり、`participant` ロールを持つユーザーはイベントを閲覧し、イベントに登録する必要があります。そのために、この API 用に 4 つのスコープを作成します。1 つはイベントの作成を許可するもの (`create:events`) 、1 つはイベントの更新を許可するもの (`update:events`) 、1 つはイベントの読み取り専用アクセスを許可するもの (`view:events`) 、そして 1 つはイベントへの登録を許可するもの (`register:events`) です。API とイベントアプリケーションはどちらも Auth0 に登録されており、API ではファーストパーティアプリケーション向けの **Allow Skipping User Consent** オプションが有効になっています。Authorization Extension をインストールし、`organizer` ロールを設定して、そのロールに `create:events` と `update:events` のスコープを作成し、ユーザー A に割り当てています。また、`participant` ロールも設定し、そのロールに `view:events` と `register:events` のスコープを作成し、ユーザー B に割り当てています。

ユーザー A は呼び出し元アプリケーションで認証され、このアプリケーションは必要なスコープを要求しますが、ファーストパーティアプリケーションであるため、ユーザーの同意は求められません。アプリは `create:events`、`update:events`、`view:events`、`register:events` の各スコープを任意の組み合わせで要求できますが、ユーザー 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 アクセスポリシー](/ja/docs/get-started/apis/api-access-policies-for-applications)を使用して、アプリケーションの API へのアクセス方法を制御できます。

<div id="learn-more">
  ## 詳しくはこちら
</div>

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