> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/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.md)を参照してください。

## 注意事項

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

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

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

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

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

## パラメーター

**DPoP** `string`

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

**auth0-forwarded-for** `string`

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

## リクエストボディ

**grant\_type** `string` *required*

使用するフローを示します。On-Behalf-Of Token Exchange の場合は、`urn:ietf:params:oauth:grant-type:token-exchange` を使用します。

**subject\_token\_type** `string` *required*

サブジェクトトークン の種類です。On-Behalf-Of Token Exchange の場合は、`urn:ietf:params:oauth:token-type:access_token` を使用します。

**subject\_token** `string` *required*

ユーザーまたはアップストリームサービスから受け取った Auth0 のアクセストークンで、現在 中間層サービス が保持しているものです。

**requested\_token\_type** `string` *required*

返却を希望するトークンの種類を示します。On-Behalf-Of Token Exchange の場合は、`urn:ietf:params:oauth:token-type:access_token` を使用します。

**client\_id** `string` *required*

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

**client\_secret** `string` *required*

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

**audience** `string` *required*

アクセスする下流 API の一意の識別子です。これは、新しいトークンを受け取って検証する下流サービスの識別子です。

**scope** `string`

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

## レスポンス

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

```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"
}
```

エージェントにリンクされたクライアントが交換を実行すると、返されたアクセストークンのデコードされた `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/"
    }
  }
}
```

## レスポンスフィールド

**access\_token** `string`

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

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

**issued\_token\_type** `string`

返されるトークンの形式を示します。これはリクエスト内の `requested_token_type` と一致します。

値: `urn:ietf:params:oauth:token-type:access_token`

**token\_type** `string`

Authorization ヘッダーで使用する認証スキームを指定します。OBO の場合、DPoP を使用していなければ `Bearer`、使用している場合は `DPoP` になります。

**expires\_in** `number`

トークンの有効期間を秒単位で示します。

**scope** `string`

(任意) 付与されたスコープ が要求されたスコープ と異なる場合にのみ含まれます。実際に付与されたスコープ のスペース区切りリストです。