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

# APIスコープ

> スコープの原則とAPIでの使用方法を理解しましょう。

API開発者は、次のことを行います。

1. ユーザーに代わって、アプリケーションがどの情報にアクセスできるようにしたいかを決める。
2. アクセスレベルをカスタムスコープとして定義する。（スコープについては、「[スコープ](/docs/ja-jp/get-started/apis/scopes)」をお読みください。）
3. スコープを識別し、呼び出しているアプリケーションが使用できるようにする。

## APIスコープの使用方法

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

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

これらの例では、トークンを使用したアクセスを制限するために、スコープを使用します。その場合、APIにトークン以外のロジックも適用し、アクセス制御を強化することができます。

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

### 例：サードパーティアプリケーションによって呼び出されるAPI

オンライン決済アプリケーションに銀行口座情報を提供するAPIをビルドするとしましょう。アプリは、複数の時点で口座残高や資金振替を読み取る必要があります。それには、APIのために2つのスコープ、つまり、口座残高の読み取りを認可するスコープ（`read:balance`）と、資金振替を認可するスコープ（`transfer:funds`）を作成します。APIは、Auth0で登録されています。

呼び出す側のアプリケーションは、ユーザーに対し、要求されたスコープへのアクセスを認可するよう要求します。ユーザーは、要求を承認または拒否します。アプリは、`read:balance`スコープを要求に含めることでユーザーの残高の読み取りアクセスを要求したり、`transfer:funds`スコープを要求に含めることで資金振替へのアクセスを要求したり、`read:balance`と`transfer:funds`の両方のスコープを要求に含めることでユーザーの残高の読み取りアクセスと資金振替へのアクセスの両方を要求できます。

さて、アプリがAPIを呼び出すとき、そこには、ユーザーが自身のコンテンツへのアクセスを認可したということを確認し、ユーザーがどのスコープを承認したかを示すトークンが含まれています。APIは、承認されたスコープに従い、ユーザーが認可した情報だけを呼び出す側のアプリケーションに提供します。

### 例：ファーストパーティアプリケーションによって呼び出されるAPI

たとえば、自分で書いたイベントアプリにデータを提供する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で登録されており、ファーストパーティアプリケーションの **［Allow Skipping User Consent（ユーザー同意のスキップの許可）］** オプションがAPIで有効になっています。認可拡張機能をインストールし、`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を呼び出すとき、そこにはトークンが含まれます。そのトークンは、認証されたユーザーのロールに関連するスコープのみに対して認可を受けていることを確認します。

### 例：バックエンドサービスによって呼び出されるAPI

たとえば、あなたは医療従事者で、MRI検査を実施する度に大量の画像データを作成するAPIを持っているとしましょう。画像データは、ローカルで6か月間保管されますが、病院が規制に準拠するためには、長期間にわたる保管が必要です。そのため、病院には、画像データを毎晩コピーしてオフサイトのコールドストレージに保管し、ローカルの医療データを6か月の保管期間の後にすべて削除するサービスがあります。

それには、APIのために2つのスコープ、つまり、画像データの読み取りアクセスを認可するスコープ（`read:images`）と、画像データの削除アクセスを認可するスコープ（`delete:images`）を作成します。APIと自動サービスは、Auth0に登録されており、自動サービスがAPIのトークンを要求することも認可されています。

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

さて、自動サービスがAPIを呼ぶとき、そこには要求されたスコープに対する認可があることを検証するトークンが含まれます。

## APIスコープの制限

アプリケーションは、API用に定義したスコープならどれでも要求に含めることができます。しかし、あらゆるスコープの使用を許可せずに、特定のユーザーに対してスコープを制限することが可能です。たとえば、アプリケーションのユーザーにロールを割り当てて、そのユーザーの代わりに行われる要求には、そのロールに割り当てられたスコープしか含められないようにします。このためには、[認可拡張機能を使用](/docs/ja-jp/customize/extensions/authorization-extension)し、カスタムルールを作成することができます。ルールの詳細については、「[Auth0 Rules](/docs/ja-jp/customize/rules)」をお読みください。

このアプローチについての理解を深めたい場合は、「[SPA+APIのアーキテクチャシナリオ](/docs/ja-jp/get-started/architecture-scenarios/spa-api/part-1)」をお読みください。具体的には、「[認可拡張機能を構成する](/docs/ja-jp/get-started/architecture-scenarios/spa-api/part-2#configure-the-authorization-extension)」セクションを参照し、認可拡張機能の構成方法や、スコープがユーザーのロールに応じて付与されるようにするカスタムルールの作成方法を確認することができます。

## もっと詳しく

* [「サンプルユースケース」の「スコープとクレーム」](/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)