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

> Découvrez l’objet API du déclencheur Action custom-token-exchange.

# Objet API

L’objet API du déclencheur Actions custom-token-exchange comprend :

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

Modifiez l’accès de la requête d’échange de jetons, par exemple en la rejetant.

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

Marquez l’échange de jetons actuel comme rejeté.

Si la requête est rejetée en raison d’un jeton de sujet non valide, nous recommandons plutôt d’utiliser api.access.rejectInvalidSubjectToken
afin de distinguer les tentatives de force brute sur le jeton de sujet des autres motifs de rejet de la requête.

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

  // 1. Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre politique d'autorisation à l'utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // si l'utilisateur est autorisé, poursuivre comme indiqué ici

};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="code" type="string">
    Le code d’erreur justifiant le rejet de l’échange de jetons. Peut être invalid\_request, server\_error ou tout code personnalisé
  </ParamField>

  <ParamField body="reason" type="string">
    Une explication claire du rejet de la demande d’échange de jetons.
  </ParamField>
</Expandable>

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

Marquez comme invalide le jeton de sujet fourni dans la requête. La requête sera alors
rejetée avec le code d’erreur "invalid\_request".

Cela indiquera aux fonctionnalités de protection contre les attaques qu’un jeton de sujet invalide a été fourni,
afin que des mesures de protection contre les attaques par force brute visant le jeton de sujet puissent être appliquées.

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

  try {
    // Valider subject_token
    const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
    // définir l’utilisateur pour la transaction
    api.authentication.setUserById(subject_token.id);

  } catch (error) {
    if (error.message === 'Invalid Token') {
      // Si le problème est précisément que subject_token n’est pas valide
      console.error('Invalid Token error');
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      // s’il survient toute autre erreur inattendue, générer une erreur de serveur
      throw error;
    }
  }

};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="reason" type="string">
    Une explication claire du rejet de la requête d’échange de jeton.
  </ParamField>
</Expandable>

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

Indique le résultat de l’authentification du jeton de sujet afin de préciser l’utilisateur auquel les jetons seront attribués.

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

Indiquez l’utilisateur associé au subject\_token en fournissant son userId. La requête d’échange de jetons émettra des jetons pour cet utilisateur.
Cet utilisateur doit déjà exister.
Remarque : l’Action Custom Token Exchange doit appeler exactement une des méthodes api.authentication.setUserByConnection ou api.authentication.setUserById.

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

  // 1. Valider subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre politique d’autorisation à l’utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Définir l’utilisateur pour la transaction
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="user_id" type="string">
    L’ID de l’utilisateur doit correspondre à un utilisateur existant.
  </ParamField>
</Expandable>

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

Indiquez l’utilisateur correspondant au subject\_token en fournissant une connexion et des attributs utilisateur.
La requête d’échange de jetons émettra des jetons pour cet utilisateur.

Il peut s’agir d’un utilisateur existant ou d’un nouvel utilisateur. Si l’utilisateur n’existe pas, il sera créé.
La propriété user\_id du profil utilisateur servira à déterminer si l’utilisateur existe déjà.

Remarque : exactement une des méthodes api.authentication.setUserByConnection et api.authentication.setUserById doit être appelée par l’Action Custom Token Exchange.

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

  // 1. Valider subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre politique d’autorisation à l’utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Définir l’utilisateur pour la transaction
  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) => {

  // Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // Créer un utilisateur, mais sans faire la vérification du courriel
  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;
};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="connection_name" type="string">
    Nom de la connexion dans laquelle l'utilisateur doit être enregistré.
  </ParamField>

  <ParamField body="user_attributes" type="customtokenexchangesetuserbyconnectionuserattributes">
    Les attributs du profil de l'utilisateur, y compris user\_id, ainsi que, facultativement, d'autres attributs comme l'adresse courriel, le nom, etc.

    Le champ user\_id est requis et doit être l'identifiant unique de l'utilisateur au sein de la connexion ;
    il sert à déterminer si l'utilisateur existe ou doit être créé. Pour les utilisateurs existants, ce user\_id
    se trouve en examinant l'array identities du profil utilisateur normalisé.

    Si l'utilisateur existe déjà, les attributs utilisateur suivants ne peuvent pas être mis à jour : email, email\_verified, phone, phone\_verified, username.
    S'ils ne correspondent pas à ceux de l'utilisateur existant, une erreur est renvoyée.

    <Expandable title="propriétés de user_attributes">
      <ParamField body="email" type="string">
        L'adresse courriel de l'utilisateur.
        Facultatif.
      </ParamField>

      <ParamField body="email_verified" type="boolean">
        Indique si cette adresse courriel est vérifiée (true) ou non vérifiée (false).
        Facultatif.
      </ParamField>

      <ParamField body="family_name" type="string">
        Le ou les noms de famille de l'utilisateur.
        Facultatif.
      </ParamField>

      <ParamField body="given_name" type="string">
        Le ou les prénoms de l'utilisateur.
        Facultatif.
      </ParamField>

      <ParamField body="name" type="string">
        Le nom complet de l'utilisateur.
        Facultatif.
      </ParamField>

      <ParamField body="nickname" type="string">
        Le surnom de l'utilisateur.
        Facultatif.
      </ParamField>

      <ParamField body="phone_number" type="string">
        Le numéro de téléphone de l'utilisateur (conforme à la recommandation E.164).
        Facultatif.
      </ParamField>

      <ParamField body="phone_verified" type="boolean">
        Indique si ce numéro de téléphone a été vérifié (true) ou non (false).
        Facultatif.
      </ParamField>

      <ParamField body="picture" type="string">
        Un URI pointant vers l'image de l'utilisateur.
        Facultatif.
      </ParamField>

      <ParamField body="user_id" type="string">
        L'identifiant unique de l'utilisateur au sein de la connexion.
      </ParamField>

      <ParamField body="username" type="string">
        Le nom d'utilisateur de l'utilisateur.
        Facultatif.
      </ParamField>

      <ParamField body="verify_email" type="boolean">
        Indique si l'utilisateur recevra un courriel de vérification après sa création (true) ou ne recevra aucun courriel (false).
        Facultatif.
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="options" type="customtokenexchangesetuserbyconnectionoptions">
    Options permettant de contrôler le comportement de la commande setUserByConnection.

    * `creationBehavior` - comportement à appliquer si aucun utilisateur ayant le user\_id spécifié n'existe dans la connexion.
      Peut être 'create\_if\_not\_exists', ce qui crée un nouvel utilisateur à l'aide des attributs utilisateur fournis ;
      ou 'none', ce qui empêche la création d'un utilisateur et renvoie une erreur si aucun utilisateur n'existe.

    * `updateBehavior` - comportement à appliquer si un utilisateur ayant le user\_id spécifié existe déjà dans la connexion.
      Peut être 'replace', ce qui remplace les attributs de l'utilisateur existant par les
      attributs utilisateur spécifiés ; ou 'none', ce qui signifie que l'utilisateur existant n'est pas modifié.

    <Expandable title="propriétés des options">
      <ParamField body="creationBehavior" type="string">
        Comportement à appliquer si aucun utilisateur ayant le user\_id spécifié n'existe dans la connexion.
        Valeurs autorisées : `create_if_not_exists`, `none`
      </ParamField>

      <ParamField body="updateBehavior" type="string">
        Comportement à appliquer si un utilisateur ayant le user\_id spécifié existe déjà dans la connexion.
        Valeurs autorisées : `none`, `replace`
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

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

Définit l’organisation de l’utilisateur associé à l’échange de jetons.

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

  // 1. Valider subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Appliquer votre politique d’autorisation à l’utilisateur
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Définir l’organisation pour la transaction
  api.authentication.setOrganization('org_xS525r979AS33MSf');

  // 4. Définir l’utilisateur pour la transaction. Vous pouvez également utiliser setUserByConnection()
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="organization_id_or_name" type="string">
    L’ID ou le nom de l’organisation à associer à l’utilisateur.
  </ParamField>
</Expandable>

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

Définissez l’acteur de l’échange de jetons afin de représenter l’entité qui agit au nom du sujet.
Doit être utilisé conjointement avec les commandes setUserById ou SetUserByConnection. L’appel à setActor est facultatif.
La réception d’un actor\_token dans la requête ne génère pas automatiquement une revendication act ; l’Action doit appeler explicitement cette méthode.
Aucun jeton d’actualisation n’est émis lorsqu’un acteur est défini pour la transaction.

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

  // 1. Valider subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
  const actor_token = await validateToken(event.transaction.actor_token, jwksUri);

  // 2. Définir l’acteur de la transaction
  api.authentication.setActor({ sub: actor_token.sub });

  // 3. Définir l’utilisateur pour la transaction
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="actor" type="actorparams">
    Objet imbriqué représentant une chaîne de délégation. Jusqu’à 4 niveaux `act` supplémentaires sont autorisés
    (5 acteurs au total, y compris l’acteur root). Pour chaque niveau, le champ `sub` est obligatoire; jusqu’à 5 propriétés
    personnalisées supplémentaires (valeurs String, Boolean ou number) peuvent être fournies.

    <Expandable title="propriétés de l’acteur">
      <ParamField body="sub" type="string" />

      <ParamField body="act" type="dictionary">
        Facultatif.

        <Expandable title="propriétés de act">
          <ParamField body="sub" type="string" />

          <ParamField body="act" type="dictionary">
            Facultatif.

            <Expandable title="propriétés de act">
              <ParamField body="sub" type="string" />

              <ParamField body="act" type="dictionary">
                Facultatif.

                <Expandable title="propriétés de act">
                  <ParamField body="sub" type="string" />

                  <ParamField body="act" type="dictionary">
                    Facultatif.

                    <Expandable title="propriétés de act">
                      <ParamField body="sub" type="string" />

                      <ParamField body="act" type="dictionary">
                        Facultatif.
                      </ParamField>
                    </Expandable>
                  </ParamField>
                </Expandable>
              </ParamField>
            </Expandable>
          </ParamField>
        </Expandable>
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

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

Demande des modifications à apporter à l’utilisateur correspondant au jeton de sujet.

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

Définissez les métadonnées propres à l’application pour l’utilisateur associé au jeton de sujet.

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

  // Définir l’utilisateur pour la transaction
  api.authentication.setUserById(subject_token.id);

  // Définir le groupe de l’utilisateur en fonction des renseignements contenus dans subject_token
  api.user.setAppMetadata('group', subject_token.group);

  return;
};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="key" type="string">
    La propriété de métadonnées à définir.
  </ParamField>

  <ParamField body="value" type="unknown">
    La valeur de la propriété de métadonnées. Définissez-la à `null` pour supprimer cette
    propriété.
  </ParamField>
</Expandable>

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

Définit les métadonnées générales de l’utilisateur correspondant au jeton de sujet.

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Valider le subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // Définir l’utilisateur pour la transaction
  api.authentication.setUserById(subject_token.id);

  // Définir preferred_locale de l’utilisateur selon les informations contenues dans subject_token
  api.user.setUserMetadata('preferred_locale', subject_token.locale);

  return;
};
```

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="key" type="string">
    La propriété de métadonnées à définir.
  </ParamField>

  <ParamField body="value" type="unknown">
    La valeur de la propriété de métadonnées. Peut être définie à `null` pour supprimer cette
    propriété.
  </ParamField>
</Expandable>

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

Stockez et récupérez des données conservées d’une exécution à l’autre.

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

Supprime, s’il existe, l’enregistrement associé à la valeur mise en cache correspondant à la clé fournie.

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="key" type="string">
    La clé de l’enregistrement du cache à supprimer.
  </ParamField>
</Expandable>

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

Récupère l’enregistrement décrivant la valeur mise en cache associée à la clé fournie,
s’il existe. Si un enregistrement est trouvé, la valeur mise en cache se trouve
dans la propriété `value` de l’objet retourné.

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="key" type="string">
    La clé de l’enregistrement stocké dans le cache.
  </ParamField>
</Expandable>

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

Stocke ou met à jour une valeur de type chaîne dans le cache sous la clé spécifiée.

Les valeurs stockées dans ce cache sont limitées au Trigger dans lequel elles
sont définies. Elles sont soumises aux [limites du cache Actions](https://auth0.com/docs/customize/actions/limitations).

Les valeurs stockées de cette façon auront une durée de vie *pouvant aller jusqu’aux* valeurs
`ttl` ou `expires_at` spécifiées. Si aucune durée de vie n’est spécifiée, une durée de vie
par défaut de 15 minutes est utilisée. Les durées de vie ne peuvent pas dépasser la durée maximale
indiquée dans les [limites du cache Actions](https://auth0.com/docs/customize/actions/limitations).

**Important** : Ce cache est conçu pour stocker des données éphémères de courte durée. Les éléments pourraient ne pas être
accessibles lors de transactions ultérieures, même s’ils n’ont pas encore atteint leur durée de vie prévue.

**Paramètres**

<Expandable title="Paramètres" defaultOpen>
  <ParamField body="key" type="string">
    La clé de l’enregistrement à stocker.
  </ParamField>

  <ParamField body="value" type="string">
    La valeur de l’enregistrement à stocker.
  </ParamField>

  <ParamField body="options" type="cachesetoptions">
    Options permettant d’ajuster le comportement du cache.
    Facultatif.

    <Expandable title="propriétés des options">
      <ParamField body="expires_at" type="number">
        L’heure d’expiration absolue, en millisecondes depuis l’époque Unix.
        Bien que les enregistrements mis en cache puissent être évincés plus tôt, ils ne
        seront jamais conservés au-delà de la valeur `expires_at` fournie.

        *Remarque* : Cette valeur ne doit pas être fournie si une valeur a également été
        fournie pour `ttl`. Si les deux options sont fournies, la date d’expiration
        la plus rapprochée sera utilisée.
        Facultatif.
      </ParamField>

      <ParamField body="ttl" type="number">
        La durée de vie de cette entrée de cache, en millisecondes.
        Bien que les valeurs mises en cache puissent être évincées plus tôt, elles ne
        seront jamais conservées au-delà de la valeur `ttl` fournie.

        *Remarque* : Cette valeur ne doit pas être fournie si une valeur a également été
        fournie pour `expires_at`. Si les deux options sont fournies, la date d’expiration
        la plus rapprochée sera utilisée.
        Facultatif.
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>