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

# トークンを取得

> On-Behalf-Of（OBO）トークン交換を使用すると、中間層サービスは受信したユーザートークンを、下流サービス向けにスコープが設定された新しいトークンに交換できます。

`POST /oauth/token`

On-Behalf-Of (OBO) トークン交換 ([RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693)) を使用すると、中間層サービスは、ユーザーにスコープが設定されたトークンを、下流サービスを呼び出すための新しいトークンに交換できます。

新しいトークンは、元のユーザーの識別情報と権限を維持したまま、下流サービス向けに特化したスコープが設定されます。これにより、そのサービスはエンドユーザーに基づいて認可を判断できます。委任チェーンは `act` (actor) クレームで追跡され、各レベルは呼び出しチェーン内のサービスを表します。詳しくは、[On-Behalf-Of Token Exchange documentation](https://auth0.com/docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange)を参照してください。

<div id="remarks">
  ## 注意事項
</div>

* リソースサーバーに関連付けられた Custom API クライアントのみが、OBO トークン交換を使用できます。Custom API クライアントには、次の要件があります。
  * `app_type` を `resource_server` に設定します。
  * `resource_server_identifier` を有効なリソースサーバー (例: `https://my-api.example.com`) に設定します。Auth0 は認可リクエストで、リソースサーバー識別子を audience パラメーターとして使用します。

* アプリケーションに発行されるスコープは、リクエストしたスコープと異なる場合があります。その場合、レスポンス JSON には `scope` パラメーターが含まれます。スコープは、ユーザーの [RBAC ポリシー](/docs/ja-jp/manage-users/access-control/rbac) に基づいて決まります。

* OBO トークン交換を行うと、[`post-login` Action trigger](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) がトリガーされます。このとき、`event.transaction.protocol` には `oauth2-token-exchange` が設定され、`event.transaction.actor` には完全な委任チェーンが記録されます。

* 委任チェーンは 5 段階までネストできます。交換時に現在のクライアントがさらに 1 段階として追加されるため、サブジェクトトークンがすでに 4 段階の `act` ネストレベルを持っている場合、OBO トークン交換は失敗します。

* API 呼び出しのたびに新しいトークンをリクエストするのではなく、アクセストークンの有効期間中はそのアクセストークンをキャッシュしてください。アクセストークンは有効期限が切れるまで再利用できます。トークン交換を繰り返すと、リソースを無駄に消費し、レイテンシーが増加し、レート制限に達する可能性があります。

<div id="parameters">
  ## パラメーター
</div>

<ParamField header="DPoP" type="string">
  リクエスト用の DPoP プルーフです。これは任意項目で、アプリケーションで [Demonstrating Proof-of-Possession](/docs/ja-jp/secure/sender-constraining/demonstrating-proof-of-possession-dpop) を使用している場合にのみ必要です。
</ParamField>

<ParamField header="auth0-forwarded-for" type="string">
  エンドユーザーの IP アドレスを文字列で指定します。サーバーサイドのシナリオで [Suspicious IP Throttling](/docs/ja-jp/secure/attack-protection/suspicious-ip-throttling) 保護を有効にしたい場合は、これを設定してください。
</ParamField>

<div id="request-body">
  ## リクエストボディ
</div>

<ParamField body="grant_type" type="string" required>
  使用するフローを示します。On-Behalf-Of Token Exchange の場合は、`urn:ietf:params:oauth:grant-type:token-exchange` を使用します。
</ParamField>

<ParamField body="subject_token_type" type="string" required>
  サブジェクトトークン の種類です。On-Behalf-Of Token Exchange の場合は、`urn:ietf:params:oauth:token-type:access_token` を使用します。
</ParamField>

<ParamField body="subject_token" type="string" required>
  ユーザーまたはアップストリームサービスから受け取った Auth0 のアクセストークンで、現在 中間層サービス が保持しているものです。
</ParamField>

<ParamField body="requested_token_type" type="string" required>
  返却を希望するトークンの種類を示します。On-Behalf-Of Token Exchange の場合は、`urn:ietf:params:oauth:token-type:access_token` を使用します。
</ParamField>

<ParamField body="client_id" type="string" required>
  Custom API クライアントの Client ID です。Custom API クライアントは、リソースサーバー (同じ identifier) に関連付けられている必要があります。他の grant type と同様に、HTTP Basic Auth を使用して Authorization ヘッダーで Client ID を渡すこともできます。
</ParamField>

<ParamField body="client_secret" type="string" required>
  Custom API クライアントの Client Secret です。他の grant type と同様に、`HTTP` Basic Auth を使用して Authorization ヘッダーで Client Secret を渡すこともできます。代替手段については、[Auth0 Authentication API リファレンスドキュメント](https://auth0.com/docs/api/authentication#authentication-methods) を参照してください。OBO トークン交換 では、`token_endpoint_auth_method` を `none` に設定できない点に注意してください。
</ParamField>

<ParamField body="audience" type="string" required>
  アクセスする下流 API の一意の識別子です。これは、新しいトークンを受け取って検証する下流サービスの識別子です。
</ParamField>

<ParamField body="scope" type="string">
  (任意) 下流呼び出しに対して要求する特定の権限を、スペース区切りのリストで指定します。指定しない場合は、対象 audience に対してユーザーに付与されているすべてのスコープが、RBAC ポリシーに基づいて含まれます。
</ParamField>

<div id="response">
  ## レスポンス
</div>

| ステータス | 説明                                                                                                        |
| ----- | --------------------------------------------------------------------------------------------------------- |
| 200   | 正常なレスポンスです。ユーザー ID を維持したまま、下流 API 用のアクセストークンを返します。                                                        |
| 400   | 不正なリクエストです。サブジェクトトークンにすでに 4 階層のネストされた `act` が含まれており、これがこの交換で拡張できる最大値である場合や、必須パラメーターが不足している場合に発生することがあります。 |
| 401   | 未認証です。サブジェクトトークンが無効か有効期限切れであるか、クライアント認証情報が誤っています。                                                         |
| 403   | アクセスが拒否されました。クライアントにトークン交換を実行する権限がないか、ユーザーにターゲットaudienceに対して要求されたスコープがありません。                              |

<ResponseExample>
  ```json 200 レスポンス theme={null}
  {
    "access_token": "eyJ...",
    "expires_in": 86400,
    "token_type": "Bearer",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
  }
  ```

  ```json 400 レスポンス（委任チェーンの上限を超過） theme={null}
  {
    "error": "invalid_request",
    "error_description": "Delegation chain (`act` claim) depth exceeds the maximum allowed limit of 4"
  }
  ```
</ResponseExample>

エージェントにリンクされたクライアントが交換を実行すると、返されたアクセストークンのデコードされた `act` クレームでは、エージェントが最も外側のactorとして配置され、サブジェクトトークンの既存の委任チェーンがネストされた内側の `act` として保持されます。

```json theme={null}
{
  "act": {
    "sub": "agt_72jbvv7LfRKYp59gtRLtkn",
    "sub_profile": "ai_agent",
    "client_id": "K1AUPhZq8mRi0Q0pjhkfu1D7y6KjDQja",
    "iss": "https://tenant.auth0.com/",
    "act": {
      "sub": "mcp_server_client_id",
      "client_id": "mcp_server_client_id",
      "sub_profile": "service ai_agent",
      "iss": "https://tenant.auth0.com/"
    }
  }
}
```

<div id="response-fields">
  ## レスポンスフィールド
</div>

<ResponseField name="access_token" type="string">
  下流 API 向けにスコープ指定された、新しい Auth0 のアクセストークンです。この [JSON Web Token (JWT)](/docs/ja-jp/secure/tokens/json-web-tokens#json-web-tokens) には、サブジェクトトークン と同じ `sub` (ユーザー ID) が含まれ、`aud` にはリクエストされた下流 API の audience が設定されます。`act` クレーム は委任チェーンを追跡します。

  [エージェントにリンクされたクライアントが交換を実行し](/docs/ja-jp/ai-agents-mcp/agents-as-principal)、下流 API でエージェントのサブジェクトクレームが有効になっている場合、エージェントは `act` クレームの最も外側のactorとなり、サブジェクトトークンからの以前の委任チェーンはネストされた内側の `act` として保持されます。詳細については、[act クレーム](/docs/ja-jp/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange#the-act-claim)を参照してください。
</ResponseField>

<ResponseField name="issued_token_type" type="string">
  返されるトークンの形式を示します。これはリクエスト内の `requested_token_type` と一致します。

  値: `urn:ietf:params:oauth:token-type:access_token`
</ResponseField>

<ResponseField name="token_type" type="string">
  Authorization ヘッダーで使用する認証スキームを指定します。OBO の場合、DPoP を使用していなければ `Bearer`、使用している場合は `DPoP` になります。
</ResponseField>

<ResponseField name="expires_in" type="number">
  トークンの有効期間を秒単位で示します。
</ResponseField>

<ResponseField name="scope" type="string">
  (任意) 付与されたスコープ が要求されたスコープ と異なる場合にのみ含まれます。実際に付与されたスコープ のスペース区切りリストです。
</ResponseField>