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

> Custom Token Exchange フローを使用して API を呼び出す方法を説明します。

# Custom Token Exchange フローを使用して API を呼び出す

Custom Token Exchange を使用するには、次のパラメーターを指定して `/oauth/token` エンドポイントに `POST` リクエストを送信します。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Custom Token Exchange で使用するサブジェクトトークンとアクタートークンは、Action コードで解釈できる限り、任意のトークン形式またはトークンタイプを使用できます。受信して受け入れるトークンについては、必ず堅牢な検証を実装してください。これを怠ると、なりすましやリプレイ攻撃などのさまざまな攻撃ベクトルに対して脆弱になり、悪意のある第三者が他人のユーザー ID で認証されたり、権限なくそのユーザーの代理として振る舞えたりするおそれがあります。

  各 `subject_token_type` は Custom Token Exchange Profile にマッピングされ、そのトランザクションを制御するために実行される Action に関連付けられます。
</Callout>

| パラメーター               | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grant_type`         | Custom Token Exchange の場合は、`urn:ietf:params:oauth:grant-type:token-exchange` を使用します。                                                                                                                                                                                                                                                                                                                                                                                                     |
| `subject_token_type` | サブジェクトトークンのタイプです。Custom Token Exchange では、`http://acme.com/legacy-token` や `urn:acme:legacy-token` のように、自身が管理する名前空間配下の任意の URI を使用できます。<br /><br />次の名前空間は予約されているため、使用できません。<ul><li>`http://auth0.com`</li><li>`https://auth0.com`</li><li>`http://okta.com`</li><li>`https://okta.com`</li><li>`urn:ietf`</li><li>`urn:auth0`</li><li>`urn:okta`</li></ul>                                                                                                                               |
| `subject_token`      | サブジェクトトークンです。Action でこれを検証し、ユーザーを識別するために使用する必要があります。                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `client_id`          | Token Exchange に使用するアプリケーションのクライアント ID です。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization ヘッダーでクライアント ID を渡すこともできます。                                                                                                                                                                                                                                                                                                                                                                   |
| `client_secret`      | Token Exchange に使用するアプリケーションのクライアントシークレットです。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization ヘッダーでクライアントシークレットを渡すこともできます。<br /><br />そのほかの方法については、[Auth0 Authentication API リファレンス](https://auth0.com/docs/api/authentication#authentication-methods)を参照してください。<br /><br />なお、Custom Token Exchange はパブリックアプリケーションでも使用できます。その場合は、[アタックプロテクション](#attack-protection) を必ず確認してください。                                                                                                         |
| `audience`           | Auth0 で定義された API 識別子です。指定しない場合は、[テナント設定](/ja/docs/get-started/tenant-settings) で設定されたデフォルトのテナントオーディエンスが使用されます。                                                                                                                                                                                                                                                                                                                                                                           |
| `scope`              | (省略可能) OAuth 2.0 のスコープパラメーターです。                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `organization`       | (省略可能) リクエストに関連付ける組織識別子です。テナントで [Use Organization Names in Authentication API](/ja/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api) が許可されている場合は、代わりに組織名を指定することもできます。リクエストがどのように処理されるかについて詳しくは、[api.authentication.setOrganization() API method](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object#api-authentication-setorganization-organization) を参照してください。 |
| `actor_token`        | (省略可能) サブジェクトユーザーに代わってデリゲーションを実行するアクターまたはプリンシパルを識別するトークンです。`actor_token_type` とあわせて指定する必要があります。                                                                                                                                                                                                                                                                                                                                                                                          |
| `actor_token_type`   | (省略可能) アクタートークンのタイプです。`actor_token` とあわせて指定する必要があります。Auth0 IDトークンの場合は、自動的なサーバー側検証を行うために `urn:ietf:params:oauth:token-type:id_token` を使用します。それ以外の値については、`subject_token_type` と同じ名前空間の制約に従ってください。                                                                                                                                                                                                                                                                                          |

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  トランザクションにアクターが設定されている場合、要求されたスコープにかかわらずリフレッシュトークンは発行されません。レスポンスからは `offline_access` スコープが除外されます。これは意図された設計です。デリゲーションされたトークンがその場の交換を超えて有効にならないようにすることで、後続の各アクセスリクエストが CTE Action の認可ロジックを経由し、デリゲーションを再検証できるようにしています。

  CTE Action は、`subject_token` に対して行うのと同等の厳密さ (たとえば暗号署名の検証) で `actor_token` を安全に検証する責任を負います。`actor_token_type` が `urn:ietf:params:oauth:token-type:id_token` の場合、Auth0 がこの検証を自動的に実行します。
</Callout>

上記に記載されていないその他の拡張パラメーターは、該当する Action の `event.request.body` に含まれます。

<div id="sample-request">
  ## リクエストの例
</div>

```bash lines theme={null}
curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scopes=openid offline_access acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:external-idp-migration' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
--data-urlencode 'organization=periscope-acme'
```

<div id="sample-request-with-actor-token">
  ## アクタートークンを使用したリクエスト例
</div>

委任認可の交換を行う場合は、`actor_token` と `actor_token_type` を含めます：

```bash lines theme={null}
curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scopes=openid acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:legacy-token' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'actor_token=eyJhbGciOiJSUzI1NiI .... kXdF9tZ3c' \
--data-urlencode 'actor_token_type=urn:ietf:params:oauth:token-type:id_token' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
```