> ## 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 Action トリガーの API オブジェクトについて説明します。

# API オブジェクト

custom-token-exchange Actions トリガーの API オブジェクトには、以下が含まれます。

<div id="apiaccess">
  ## `api.access`
</div>

リクエストの拒否など、トークン交換リクエストへのアクセスを変更します。

<div id="apiaccessdenycode-reason">
  ### `api.access.deny(code, reason)`
</div>

現在のトークン交換を拒否として扱います。

無効なサブジェクトトークンを理由にリクエストを拒否する場合は、サブジェクトトークンに対するブルートフォース試行と、リクエストを拒否するその他の理由を区別するため、代わりに api.access.rejectInvalidSubjectToken を使用することを推奨します。

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに認可ポリシーを適用する
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // ユーザーが認可されている場合は、以下のように処理を続行する

};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="code" type="string">
    トークン交換を拒否する根拠となるエラーコード。invalid\_request、server\_error、または任意のカスタムコードを指定できます
  </ParamField>

  <ParamField body="reason" type="string">
    トークン交換リクエストを拒否する理由を、人が理解しやすい形式で説明します。
  </ParamField>
</Expandable>

<div id="apiaccessrejectinvalidsubjecttokenreason">
  ### `api.access.rejectInvalidSubjectToken(reason)`
</div>

リクエストで指定されたサブジェクトトークンを無効として扱います。これにより、リクエストは
"invalid\_request" エラーコードで拒否されます。

また、無効なサブジェクトトークンが指定されたことが攻撃対策機能に通知されるため、
サブジェクトトークンに対するブルートフォース攻撃を防ぐための保護を適用できます。

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  try {
    // subject_token を検証
    const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
    // トランザクションに使用するユーザーを設定
    api.authentication.setUserById(subject_token.id);

  } catch (error) {
    if (error.message === 'Invalid Token') {
      // subject_token が無効であることが原因の場合
      console.error('Invalid Token error');
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      // その他の予期しないエラーが発生した場合は、サーバーエラーをスロー
      throw error;
    }
  }

};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="reason" type="string">
    トークン交換リクエストを拒否する理由を、人が理解しやすい形式で説明します。
  </ParamField>
</Expandable>

<div id="apiauthentication">
  ## `api.authentication`
</div>

サブジェクトトークンの認証結果を示し、トークンの発行先となるユーザーを指定します。

<div id="apiauthenticationsetuserbyiduser_id">
  ### `api.authentication.setUserById(user_id)`
</div>

userId を指定して、subject\_token に対応するユーザーを指定します。トークン交換リクエストでは、このユーザーのトークンが発行されます。
指定するユーザーは既存のユーザーである必要があります。
注: カスタムトークン交換 Action では、api.authentication.setUserByConnection または api.authentication.setUserById のいずれか一方のみを呼び出す必要があります。

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに対して認可ポリシーを適用
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. トランザクションのユーザーを設定
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="user_id" type="string">
    既存ユーザーのIDを指定します。
  </ParamField>
</Expandable>

<div id="apiauthenticationsetuserbyconnectionconnection_name-user_attributes-options">
  ### `api.authentication.setUserByConnection(connection_name, user_attributes, options)`
</div>

接続とユーザー属性を指定して、subject\_token に対応するユーザーを設定します。
トークン交換リクエストでは、このユーザーのトークンが発行されます。

既存のユーザーまたは新規ユーザーを指定できます。ユーザーが存在しない場合は作成されます。
ユーザー\_profile の user\_id プロパティを使用して、ユーザーがすでに存在するかどうかを判断します。

注: カスタムトークン交換 Action では、api.authentication.setUserByConnection または api.authentication.setUserById のいずれか一方を必ず呼び出す必要があります。

```js Set user by connection with full profile attributes theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに認可ポリシーを適用する
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. トランザクションのユーザーを設定する
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: subject_token.email_verified,
      phone_number: subject_token.phone_number,
      phone_verified: subject_token.phone_number_verified,
      username: subject_token.preferred_username,
      name: subject_token.name,
      given_name: subject_token.given_name,
      family_name: subject_token.family_name,
      nickname: subject_token.nickname,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};
```

```js Create a user without verifying email theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // ユーザーを作成するが、メールアドレスは検証しない
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: false,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="connection_name" type="string">
    ユーザーを保存する接続の名前。
  </ParamField>

  <ParamField body="user_attributes" type="customtokenexchangesetuserbyconnectionuserattributes">
    user\_id を含むユーザーのプロファイル属性。email、name などのその他の属性は任意です。

    user\_id フィールドは必須で、接続内でユーザーを一意に識別する識別子である必要があります。
    これは、ユーザーが存在するか、作成が必要かを判断するために使用されます。既存ユーザーの場合、この user\_id
    は正規化されたユーザープロファイルの identities 配列を確認して取得できます。

    ユーザーがすでに存在する場合、次のユーザー属性は更新できません: email、email\_verified、phone、phone\_verified、username。
    これらが既存ユーザーの属性と一致しない場合、エラーが返されます。

    <Expandable title="user_attributes プロパティ">
      <ParamField body="email" type="string">
        ユーザーのメールアドレス。
        任意。
      </ParamField>

      <ParamField body="email_verified" type="boolean">
        このメールアドレスが確認済み (true) か、未確認 (false) か。
        任意。
      </ParamField>

      <ParamField body="family_name" type="string">
        ユーザーの姓。
        任意。
      </ParamField>

      <ParamField body="given_name" type="string">
        ユーザーの名。
        任意。
      </ParamField>

      <ParamField body="name" type="string">
        ユーザーのフルネーム。
        任意。
      </ParamField>

      <ParamField body="nickname" type="string">
        ユーザーのニックネーム。
        任意。
      </ParamField>

      <ParamField body="phone_number" type="string">
        ユーザーの電話番号 (E.164 の推奨形式) 。
        任意。
      </ParamField>

      <ParamField body="phone_verified" type="boolean">
        この電話番号が確認済み (true) か、未確認 (false) か。
        任意。
      </ParamField>

      <ParamField body="picture" type="string">
        ユーザーのプロフィール画像を指す URI。
        任意。
      </ParamField>

      <ParamField body="user_id" type="string">
        接続内でユーザーを一意に識別する識別子。
      </ParamField>

      <ParamField body="username" type="string">
        ユーザーのユーザー名。
        任意。
      </ParamField>

      <ParamField body="verify_email" type="boolean">
        作成後にユーザーへ確認メールを送信するか (true) 、送信しないか (false) 。
        任意。
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="options" type="customtokenexchangesetuserbyconnectionoptions">
    setUserByConnection コマンドの動作を制御するオプション。

    * `creationBehavior` - 接続内に指定した user\_id を持つユーザーが存在しない場合に適用する動作。
      'create\_if\_not\_exists' を指定すると、指定されたユーザー属性を使用して新しいユーザーが作成されます。
      'none' を指定すると、ユーザーは作成されず、ユーザーが存在しない場合はエラーが返されます。

    * `updateBehavior` - 接続内に指定した user\_id を持つユーザーがすでに存在する場合に適用する動作。
      'replace' を指定すると、既存ユーザーの属性が指定された
      ユーザー属性に置き換えられます。'none' を指定すると、既存ユーザーは変更されません。

    <Expandable title="options プロパティ">
      <ParamField body="creationBehavior" type="string">
        接続内に指定した user\_id を持つユーザーが存在しない場合に適用する動作。
        許可される値: `create_if_not_exists`、`none`
      </ParamField>

      <ParamField body="updateBehavior" type="string">
        接続内に指定した user\_id を持つユーザーがすでに存在する場合に適用する動作。
        許可される値: `none`、`replace`
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

<div id="apiauthenticationsetorganizationorganization_id_or_name">
  ### `api.authentication.setOrganization(organization_id_or_name)`
</div>

トークン交換に関連付けられたユーザーのorganizationを設定します。

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. ユーザーに対して認可ポリシーを適用する
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. トランザクションに organization を設定する
  api.authentication.setOrganization('org_xS525r979AS33MSf');

  // 4. トランザクションにユーザーを設定する。setUserByConnection() を使ってもよい
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="organization_id_or_name" type="string">
    ユーザーに設定するorganizationのIDまたは名前。
  </ParamField>
</Expandable>

<div id="apiauthenticationsetactoractor">
  ### `api.authentication.setActor(actor)`
</div>

サブジェクトに代わって操作を行うエンティティを表すため、トークン交換のアクターを設定します。
setUserById または SetUserByConnection コマンドと併用する必要があります。setActor の呼び出しは任意です。
リクエストで actor\_token を受信しても、act claim が自動的に生成されることはありません。Action でこのメソッドを明示的に呼び出す必要があります。
トランザクションにアクターが設定されている場合、リフレッシュトークンは発行されません。

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
  const actor_token = await validateToken(event.transaction.actor_token, jwksUri);

  // 2. トランザクションの actor を設定する
  api.authentication.setActor({ sub: actor_token.sub });

  // 3. トランザクションのユーザーを設定する
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="actor" type="actorparams">
    委譲チェーンを表すネストされたオブジェクトです。`act` レベルは最大4つまで追加できます
    (root actorを含めて合計5つのactor) 。各レベルで `sub` フィールドが必須です。さらに、最大5つの
    カスタムプロパティ (string、boolean、numberの値) を指定できます。

    <Expandable title="actor プロパティ">
      <ParamField body="sub" type="string" />

      <ParamField body="act" type="dictionary">
        任意です。

        <Expandable title="act プロパティ">
          <ParamField body="sub" type="string" />

          <ParamField body="act" type="dictionary">
            任意です。

            <Expandable title="act プロパティ">
              <ParamField body="sub" type="string" />

              <ParamField body="act" type="dictionary">
                任意です。

                <Expandable title="act プロパティ">
                  <ParamField body="sub" type="string" />

                  <ParamField body="act" type="dictionary">
                    任意です。

                    <Expandable title="act プロパティ">
                      <ParamField body="sub" type="string" />

                      <ParamField body="act" type="dictionary">
                        任意です。
                      </ParamField>
                    </Expandable>
                  </ParamField>
                </Expandable>
              </ParamField>
            </Expandable>
          </ParamField>
        </Expandable>
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

<div id="apiuser">
  ## `api.user`
</div>

サブジェクトトークンに対応するユーザーの変更をリクエストします。

<div id="apiusersetappmetadatakey-value">
  ### `api.user.setAppMetadata(key, value)`
</div>

サブジェクトトークンに対応するユーザーのアプリケーション固有のメタデータを設定します。

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // トランザクションのユーザーを設定する
  api.authentication.setUserById(subject_token.id);

  // subject_token に含まれる情報に基づいてユーザーグループを設定する
  api.user.setAppMetadata('group', subject_token.group);

  return;
};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="key" type="string">
    設定するメタデータプロパティ。
  </ParamField>

  <ParamField body="value" type="unknown">
    メタデータプロパティ値。`null` を設定すると、
    メタデータプロパティを削除できます。
  </ParamField>
</Expandable>

<div id="apiusersetusermetadatakey-value">
  ### `api.user.setUserMetadata(key, value)`
</div>

サブジェクトトークンに対応するユーザーの一般メタデータを設定します。

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // subject_token を検証する
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // トランザクションのユーザーを設定する
  api.authentication.setUserById(subject_token.id);

  // subject_token に含まれる情報に基づいて、ユーザーの preferred_locale を設定する
  api.user.setUserMetadata('preferred_locale', subject_token.locale);

  return;
};
```

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="key" type="string">
    設定するメタデータプロパティ。
  </ParamField>

  <ParamField body="value" type="unknown">
    メタデータプロパティの値。この値を `null` に設定すると、メタデータプロパティを削除できます。
  </ParamField>
</Expandable>

<div id="apicache">
  ## `api.cache`
</div>

実行をまたいで保持されるデータを保存・取得します。

<div id="apicachedeletekey">
  ### `api.cache.delete(key)`
</div>

指定されたキーにキャッシュ値を表すレコードが存在する場合、そのレコードを削除します。

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="key" type="string">
    削除するキャッシュレコードのキー。
  </ParamField>
</Expandable>

<div id="apicachegetkey">
  ### `api.cache.get(key)`
</div>

指定されたキーにキャッシュ内のレコードが存在する場合、そのキャッシュ値に関するレコードを取得します。レコードが見つかった場合、キャッシュ値は返されるオブジェクトの `value` プロパティに格納されています。

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="key" type="string">
    キャッシュに保存されているレコードのキー。
  </ParamField>
</Expandable>

<div id="apicachesetkey-value-options">
  ### `api.cache.set(key, value, options)`
</div>

指定したキーに文字列値をキャッシュへ保存または更新します。

このキャッシュに保存された値は、設定されたトリガーのスコープ内でのみ使用できます。
これらの値には、[Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations) が適用されます。

この方法で保存された値の有効期間は、指定した
`ttl` または `expires_at` の値までです。有効期間が指定されていない場合は、デフォルトで
15 分となります。有効期間は、[Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations) に記載されている最大
期間を超えることはできません。

**重要**: このキャッシュは、短期間のみ保持する一時的なデータ用に設計されています。指定された有効期間内であっても、後続のトランザクションでは
項目を利用できない場合があります。

**パラメータ**

<Expandable title="パラメータ" defaultOpen>
  <ParamField body="key" type="string">
    保存するレコードのキー。
  </ParamField>

  <ParamField body="value" type="string">
    保存するレコードの値。
  </ParamField>

  <ParamField body="options" type="cachesetoptions">
    キャッシュの動作を調整するためのオプション。
    任意。

    <Expandable title="options プロパティ">
      <ParamField body="expires_at" type="number">
        Unix エポックからのミリ秒単位の絶対的な有効期限。
        キャッシュされたレコードはそれより前に削除される場合がありますが、
        指定した `expires_at` を超えて保持されることはありません。

        *注*: `ttl` の値も指定されている場合は、この値を
        指定しないでください。両方のオプションが指定されている場合は、
        2 つのうち早い方の有効期限が使用されます。
        任意。
      </ParamField>

      <ParamField body="ttl" type="number">
        このキャッシュエントリのミリ秒単位の有効期間。
        キャッシュ値はそれより前に削除される場合がありますが、
        指定した `ttl` を超えて保持されることはありません。

        *注*: `expires_at` の値も指定されている場合は、この値を
        指定しないでください。両方のオプションが指定されている場合は、
        2 つのうち早い方の有効期限が使用されます。
        任意。
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>