> ## Documentation Index
> Fetch the complete documentation index at: https://auth0-cq3uo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions Triggers: post-login - API Object

The API object for the post-login Actions trigger includes:

## `api.access`

Modify the user's login access, such as by rejecting the login attempt.

### `api.access.deny(reason)`

Mark the current login attempt as denied. This will prevent the end-user
from completing the login flow. This will *NOT* cancel other
user-related side effects (such as metadata changes) requested by this
Action. The login flow will immediately stop following the completion of
this action and no further Actions will be executed.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>reason</code></td>

      <td>
        <p>
          <em>String</em>. A human-readable explanation for rejecting the
          login. This is sent as <code>error\_description</code> to the application that initiated the request.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.accessToken`

Request changes to the access token being issued.

### `api.accessToken.setCustomClaim(name, value)`

Set a custom claim on the Access Token that will be issued upon completion
of the login flow.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>name</code></td>

      <td>
        <p>
          <em>String</em>. Name of the claim (note that this may need to be a
          fully-qualified URL).
        </p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p><em>Any value</em>. The value of the claim.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.accessToken.addScope(scope)`

Add a scope on the Access Token that will be issued upon completion of the login flow.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>scope</code></td>

      <td>
        <p>
          <em>String</em> The scope to be added.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.accessToken.removeScope(scope)`

Remove a scope on the Access Token that will be issued upon completion of the login flow.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>scope</code></td>

      <td>
        <p>
          <em>String</em> The scope to be removed.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.authentication`

Request changes to the authentication state of the current user's session.

### `api.authentication.recordMethod(provider_url)`

Indicate that a custom authentication method has been completed in the
current session. This method will then be available in the
`event.authentication.methods` array in subsequent logins.

**Important**: This API is only available from within the
`onContinuePostLogin` function for
`PostLogin` Actions. In other words, this may be used to record
the completion of a custom authentication method after redirecting the user
via  `api.redirect.sendUserTo()`.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>provider\_url</code></td>

      <td>
        <p>
          <em>String</em>. A url representing the identity of the custom
          authenticated method that was completed.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.authentication.challengeWith(factor, options)`

Challenge the user with one or more specified multifactor authentication factors. This method presents the default challenge first, then allows the user to select a different option if additional factors have been supplied. If the user has not enrolled in any of the factors supplied (including both the default and any additional factors), the command fails.

**Note**: This method overrides existing policies and rules that enable or disable MFA in a tenant.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>factor</code></td>

      <td>
        <p>
          <em>Object</em>. An object containing the <code>type</code> field. <code>type</code> is a string used to specify the default MFA factor or factors used to challenge the user.
        </p>

        <p>Supported values include:</p>

        <ul>
          <li><code>otp</code></li>
          <li><code>recovery-code</code></li>
          <li><code>email</code></li>
          <li><code>push-notification</code></li>

          <ul>
            <li><code>otpFallback</code>When set to <code>false</code>, the user cannot use the OTP fallback option of the push notification factor. </li>
          </ul>

          <li><code>phone</code></li>

          <ul>
            <li><code>preferredMethod: voice</code></li>
            <li><code>preferredMethod: sms</code></li>
            <li><code>preferredMethod: both</code></li>
          </ul>

          <li><code>webauthn-platform</code></li>
          <li><code>webauthn-roaming</code></li>
        </ul>

        <p>Example</p>

        ```js lines theme={null}
        api.authentication.challengeWith({ 
          type: 'phone', 
          options: { preferredMethod: 'both'} 
        });
        ```
      </td>
    </tr>

    <tr>
      <td><code>options</code></td>

      <td>
        <p><em>Optional object</em>. An object containing the optional <code>additionalFactors</code> field. </p>
        <p><code>additionalFactors</code> is an array used to specify other factors a user can choose from when completing the MFA challenge. Supports the same values as the <code>type</code> field. </p>
        <p>Example</p>

        ```js lines theme={null}
        api.authentication.challengeWith({
          type: 'otp'
        }, {
          additionalFactors: [{
            type: 'push-notification'
          }, {
            type: 'phone'
          }]
        })
        ```
      </td>
    </tr>
  </tbody>
</table>

### `api.authentication.challengeWithAny(factors)`

Trigger an MFA challenge and allow the user to select their preferred factor from the supplied list. This method presents a factor picker to the user rather than a specific challenge, in accordance with the following conditions:

* If two or more factors are specified, a factor picker displays to the user.
* If the user has only enrolled in one of the specified factors (or only one factor is specified), the factor picker is skipped.
* If the user has not enrolled in any of the specified factors, the challenge command fails.

**Note**: This method overrides existing policies and rules that enable or disable MFA in a tenant.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>factors</code></td>

      <td>
        <p>
          <em>Array</em>. An array of objects that includes the <code> type</code> field. <code> type</code> is a string used to specify an MFA factor the user can choose from when challenged.
        </p>

        <p>Supported values include:</p>

        <ul>
          <li><code>otp</code></li>
          <li><code>recovery-code</code></li>
          <li><code>email</code></li>
          <li><code>push-notification</code></li>

          <ul>
            <li><code>otpFallback</code>When set to <code>false</code>, the user cannot use the OTP fallback option of the push notification factor. </li>
          </ul>

          <li><code>phone</code></li>

          <ul>
            <li><code>preferredMethod: voice</code></li>
            <li><code>preferredMethod: sms</code></li>
            <li><code>preferredMethod: both</code></li>
          </ul>

          <li><code>webauthn-platform</code></li>
          <li><code>webauthn-roaming</code></li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

### `api.authentication.enrollWith(factor, options)`

Prompt the user to enroll with a specific MFA factor. This method prompts the user to enroll with a default factor, but can optionally allow the user to select a different option if additional factors have been supplied. If the user has already enrolled in all of the supplied factors (including both the default value and any additional factors), the command fails.

**Note**: This method overrides existing policies and rules that enable or disable MFA in a tenant.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>factor</code></td>

      <td>
        <p>
          <em>Object</em>. An object containing the <code>type</code> field. <code>type</code> is a string used to specify the default MFA factor the user is prompted to enroll.
        </p>

        <p>Supported values include:</p>

        <ul>
          <li><code>otp</code></li>
          <li><code>recovery-code</code></li>
          <li><code>push-notification</code></li>
          <li><code>phone</code></li>

          <ul>
            <li><code>preferredMethod: voice</code></li>
            <li><code>preferredMethod: sms</code></li>
            <li><code>preferredMethod: both</code></li>
          </ul>

          <li><code>webauthn-platform</code></li>
          <li><code>webauthn-roaming</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>options</code></td>

      <td>
        <p><em>Optional object</em>. An object containing the optional <code>additionalFactors</code> field. </p>
        <p><code>additionalFactors</code> is an array used to specify other factors a user can choose from during enrollment. Supports the same values as the <code>type</code> field. </p>
        <p>Example</p>

        ```js lines theme={null}
        api.authentication.enrollWith({
          type: 'otp'
        }, {
          additionalFactors: [{
            type: 'push-notification'
          }, {
            type: 'phone'
          }]
        })
        ```

        <p />

        <p>Example</p>

        ```js lines theme={null}
        api.authentication.enrollWith({
          type: 'otp'
        }, {
          additionalFactors: [{
            type: 'push-notification'
          }, {
            type: 'phone'
          }]
        })
        ```
      </td>
    </tr>
  </tbody>
</table>

### `api.authentication.enrollWithAny(factors)`

Prompt the user to select an MFA factor to enroll in from the supplied list. This method presents a factor picker to the user rather than a default factor prompt, in accordance with the following conditions:

* If two or more factors are specified, the factor picker displays to the user.
* If the user has already enrolled in all supplied factors except one, the factor picker is skipped, and the user is prompted to enroll in the remaining factor.
* If the user has already enrolled in all of the supplied factors, the command fails.

**Note**: This method overrides existing policies and rules that enable or disable MFA in a tenant.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>factors</code></td>

      <td>
        <p>
          <em>Array</em>. An array of objects that includes the <code> type</code> field. <code> type</code> is a string used to specify the default MFA factor the user is prompted to enroll.
        </p>

        <p>Supported values include:</p>

        <ul>
          <li><code>otp</code></li>
          <li><code>recovery-code</code></li>
          <li><code>push-notification</code></li>
          <li><code>phone</code></li>

          <ul>
            <li><code>preferredMethod: voice</code></li>
            <li><code>preferredMethod: sms</code></li>
            <li><code>preferredMethod: both</code></li>
          </ul>

          <li><code>webauthn-platform</code></li>
          <li><code>webauthn-roaming</code></li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

### `api.authentication.setPrimaryUser(primary_user_id)`

Change the primary user for the login transaction.

In scenarios that require linking users, the user identity used to initiate the login may no longer exist as a discrete user. That identity may now be a secondary identity of an existing user. In such situations, the `setPrimaryUser()` function can be used to indicate that the subject of the login should be changed.

Important:

* Insecurely linking accounts can allow malicious actors to access legitimate user accounts, your tenant should request authentication for both accounts before linking occurs.
* The identity used to authenticate the login must be among the secondary identities of the user referenced by `primary_user_id`. The login will fail and tokens will not be issued otherwise.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>primary\_user\_id</code></td>

      <td>
        <p>
          <em>String</em>. The user ID of the user for whom tokens should be issued (the `sub` claim).
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.cache`

Store and retrieve data that persists across executions.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied key if it exists.

Returns a `CacheWriteResult` object with  `type: "success"` if a value was removed from the cache. A failed operation returns `type: "error"`. For errors, the returned object will have a
`code` property that indicates the nature of the failure.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>key</code></td>

      <td>
        <p><em>String</em>. The key of the record stored in the cache.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied
`key`, if it exists. If a record is found, the cached value can
be found at the `value` property of the returned object.

Returns a cache record if an item is found in the cache for the supplied
`key`. Cache records are objects with a
`value` property holding the cached value as well as an
`expires_at` property indicating the maximum expiry of
the record in milliseconds since the Unix epoch.

**Important:**
This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their
lifetime.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>key</code></td>

      <td>
        <p><em>String</em>. The key of the record stored in the cache.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.cache.set(key, value, [options])`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they are set.
They are subject to the
[Actions Cache Limits](/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of up to the specified
`ttl` or `expires_at` values. If no lifetime is
specified, a default lifetime of 15 minutes will be used. Lifetimes may
not exceed the maximum duration listed at
[Actions Cache Limits](/docs/customize/actions/limitations).

Returns `CacheWriteSuccess` if the values are stored successfully. Otherwise, you will receive `CacheWriteError`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>key</code></td>

      <td>
        <p><em>String</em>. The key of the record stored in the cache.</p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p><em>String</em>. The value of the record to be stored.</p>
      </td>
    </tr>

    <tr>
      <td><code>options</code></td>

      <td>
        <p><em>Optional object</em>. Options for adjusting cache behavior.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.expires\_at</code></td>

      <td>
        <p>
          <em>Optional number</em>. The absolute expiry time in milliseconds
          since the unix epoch. While cached records may be evicted earlier,
          they will never remain beyond the the supplied
          <code>expires\_at</code>.
        </p>

        <p>
          <em>Note:</em> This value should not be supplied if a value was also
          provided for <code>ttl</code>. If both options are supplied, the
          earlier expiry of the two will be used.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.ttl</code></td>

      <td>
        <p>
          <em>Optional number</em>. The time-to-live value of this cache entry
          in milliseconds. While cached values may be evicted earlier, they
          will never remain beyond the the supplied <code>ttl</code>.
        </p>

        <p>
          <em>Note:</em> This value should not be supplied if a value was also
          provided for <code>expires\_at</code>. If both options are supplied,
          the earlier expiry of the two will be used.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.idToken`

Request changes to the ID token being issued.

### `api.idToken.setCustomClaim(name, value)`

Set a custom claim on the ID token that will be issued upon completion of
the login flow.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>name</code></td>

      <td>
        <p>
          <em>String</em>. Name of the claim (note that this may need to be a
          fully-qualified URL).
        </p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p><em>Any value</em>. The value of the claim.</p>
      </td>
    </tr>
  </tbody>
</table>

## `api.multifactor`

Set the requirement for multifactor authentication on the login attempt.

### `api.multifactor.enable(provider, options)`

Enable multifactor authentication for this login flow. When enabled, users
must complete the configured multifactor challenge. The actual multifactor
challenge will be deferred to the end of the login flow.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>provider</code></td>

      <td>
        <p>
          <em>String</em>. The name of the multifactor provider to use or the
          value <code>any</code> to use any of the configured providers.
        </p>

        <p>Supported values include:</p>

        <ul>
          <li><code>any</code> Use any of the configured challenges.</li>
          <li><code>duo</code> Use the Duo multifactor provider.</li>

          <li>
            <code>google-authenticator</code> Use the Google Authenticator
            provider.
          </li>

          <li><code>guardian</code> Use the Guardian provider.</li>
          <li><code>none</code> Use none of the configured challenges to prevent the MFA flow from triggering.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>options</code></td>

      <td>
        <p>
          <em>Optional object</em>. Additional options for enabling
          multifactor challenges.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.allowRememberBrowser</code></td>

      <td>
        <p>
          <em>Optional boolean</em>. When provider is set to <code>google-authenticator</code> or <code>duo</code>, the user is prompted for MFA once every 30 days. When provider is set to <code>guardian</code>, the MFA prompt displays the enrollment checkbox for users to choose whether or not to enroll. Defaults to <code>false</code>. To learn more, read <a href="/docs/secure/multi-factor-authentication/customize-mfa ">Customize Multi-Factor Authentication Pages </a>
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.providerOptions</code></td>

      <td>
        <p>
          <em>Optional object</em>. Additional options to configure the
          challenge, only available for the <code>duo</code> provider.
        </p>

        <p>Supported options include:</p>

        <ul>
          <li>
            <code>host</code> <em>String</em>. This is the API hostname value
            from your Duo account.
          </li>

          <li>
            <code>ikey</code> <em>String</em>. This is the Client ID
            (previously Integration key) value from your Duo account.
          </li>

          <li>
            <code>skey</code> <em>String</em>. This is the Client secret
            (previously Secret key) value from your Duo account.
          </li>

          <li>
            <code>username</code> <em>Optional string</em>. Use some attribute
            of the profile as the username in DuoSecurity. This is also useful
            if you already have your users enrolled in Duo.
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

## `api.redirect`

### `api.redirect.encodeToken(options)`

Create a session token suitable for using as a query string parameter
redirect target (via `sendUserTo`) that contains data whose
authenticity must be provable by the target endpoint. The target endpoint
can verify the authenticity and integrity of the data by checking the
JWT's signature using a shared secret.

Returns a JWT string.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>options</code></td>

      <td>
        <p>
          <em>Options</em>. Configure how sensitive data is encoded into the
          query parameters of the resulting url.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.expiresInSeconds</code></td>

      <td>
        <p>
          <em>Number</em>. Number of seconds before this token will expire
          (defaults to 900).
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.payload</code></td>

      <td>
        <p>
          <em>Options</em>. The data intended to be passed to the target of
          the redirect and whose authenticity and integrity must be
          provable.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.secret</code></td>

      <td>
        <p>
          <em>String</em>. A secret that will be used to sign a JWT that is
          shared with the redirect target. The secret value should be stored
          as a secret and retrieved using
          <code>event.secrets\['SECRET\_NAME']</code>.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.redirect.sendUserTo(url, options)`

Trigger a browser redirect to the target `url` immediately after this
action completes.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>url</code></td>

      <td>
        <p><em>String</em>. The url in which to redirect the user.</p>
      </td>
    </tr>

    <tr>
      <td><code>options</code></td>

      <td>
        <p>
          <em>Options</em>. An object representing additional query string
          parameters that should be appended to the redirect URL.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.query</code></td>

      <td>
        <p>
          <em>Options</em>. Additional query string parameters that should
          be appended to the redirect URL.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.redirect.validateToken(options)`

Retrieve the data encoded in a JWT token passed to the
`/continue` endpoint while verifying the authenticity and
integrity of that data.

Returns payload of the JWT token.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>options</code></td>

      <td>
        <p>
          <em>Options</em>. Options for retrieving the data encoded in a JWT
          token passed to the <code>/continue</code> endpoint following a
          redirect.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options.secret</code></td>

      <td>
        <p><em>String</em>. Secret used to encode the token.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.tokenParameterName</code></td>

      <td>
        <p>
          <em>String</em>. The name of the query or body parameter that was
          sent to the <code>/continue</code> endpoint. (defaults to
          <code>session\_token</code>
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.refreshToken`

Manage refresh tokens, such as by revoking a refresh token.

### `api.refreshToken.revoke(reason)`

Reject the current token exchange and revoke the refresh token. This will
prevent the user from completing the flow and no further Actions are
executed.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>reason</code></td>

      <td>
        <p>
          <em>String</em>. A human-readable explanation for rejecting the
          refresh token. This is sent as error\_description to the application
          that initiated the request.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.refreshToken.setExpiresAt(absolute)`

Set a new absolute expiration date for a specified refresh token.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>absolute</code></td>

      <td>
        <p>
          <em>Number</em>. The absolute expiry time in milliseconds since the unix epoch.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.refreshToken.setIdleExpiresAt(idle)`

Set a new inactivity expiration date for a specified refresh token.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>idle</code></td>

      <td>
        <p><em>Number</em>. The inactivity expiry time in milliseconds since the unix epoch.</p><p>This method sets the refresh token inactivity timeout for the current interaction. If the method is not reapplied, subsequent successful interactions will override the inactivity timeout using the refresh token inactivity timeout settings.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.rules`

Get information about the Rules that have run during the current transaction.

### `api.rules.wasExecuted(ruleId)`

Check whether a specific Rule has been executed prior to this Action in the current transaction. This can be used to avoid running logic that has been duplicated from that Rule into this Action during migration to Actions.

This method returns `true` when the Rule with the provided ID has been executed in this transaction and `false` when it has not..

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>ruleId</code></td>

      <td>
        <p>
          String. The Rule ID to check.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.samlResponse`

Modify the SAML Response for the user that is logging in.

### `api.samlResponse.setAttribute(attribute, value)`

Set a custom SAML attribute.

A failed operation throws an `Error`. For errors, the returned
object has a message that indicates the nature of the failure.

The value must be of type `SAMLValue`, which can be
`string | number | boolean | null | Array`

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>attribute</code></td>

      <td>
        <p><em>String</em>. The SAML attribute to be set.</p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p>
          <em>SAMLValue</em>. The value of the SAML assertion. This may be set
          to <code>null</code> to remove the attribute property.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setAudience(audience)`

Alter the audience of the SAML Response. Default is the issuer on
SAMLRequest.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>audience</code></td>

      <td>
        <p><em>String</em>. The SAML audience to be set.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setIssuer(issuer)`

Alter the issuer of the SAML Response. Default issuer is `urn:TENANT`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>issuer</code></td>

      <td>
        <p><em>String</em>. The SAML issuer to be set.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setEncryptionPublicKey(publicKey)`

Optionally specify a public key used to encrypt the SAML assertion. The
public key should be obtained from the service provider. Both the public key
and certificate must be specified.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>publicKey</code></td>

      <td>
        <p><em>String</em>. The public key to be set.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setRecipient(recipient)`

Alter the recipient of the SAML assertion (SubjectConfirmationData). Default
is `AssertionConsumerUrl` on `SAMLRequest` or callback
URL if no SAMLRequest was sent.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>recipient</code></td>

      <td>
        <p><em>String</em>. The SAML recipient to be set.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setCreateUpnClaim(createUpnClaim)`

Dictates if a UPN claim should be created. Default is `true`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createUpnClaim</code></td>

      <td>
        <p><em>Boolean</em> Toggle to create a UPN claim.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setPassthroughClaimsWithNoMapping(passthroughClaimsWithNoMapping)`

If `true` (default), for each claim that is not mapped to the
common profile, Auth0 passes through those in the output assertion. If
`false`, those claims won't be mapped.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>passthroughClaimsWithNoMapping</code></td>

      <td>
        <p>
          <em>Boolean</em> Should claims should be mapped to the output
          assertion.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setMapUnknownClaimsAsIs(mapUnknownClaimsAsIs)`

If `passthroughClaimsWithNoMapping` is `true` and this
is `false` (default), for each claim not mapped to the common
profile Auth0 adds a prefix [http://schema.auth0.com](http://schema.auth0.com). If `true`,
it will pass through the claim as-is.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>mapUnknownClaimsAsIs</code></td>

      <td>
        <p><em>Boolean</em> Should claims should be mapped as-is.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setMapIdentities(mapIdentities)`

If `true` (default), this adds more information in the token such
as the provider (Google, ADFS, AD, etc.) and the access token, if available

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>mapIdentities</code></td>

      <td>
        <p><em>Boolean</em> Should identities be mapped.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setDestination(destination)`

Destination of the SAML response. If not specified, it will be
AssertionConsumerUrl of SAMLRequest or callback URL if there was no
SAMLRequest.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>destination</code></td>

      <td>
        <p><em>String</em> Destination of the SAML response.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setRelayState(relayState)`

Alter the RelayState of the SAML response. Default is `RelayState` on `SAMLRequest`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>relayState</code></td>

      <td>
        <p><em>String</em> RelayState of the SAML response.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setLifetimeInSeconds(lifetimeInSeconds)`

Expiration of the token in seconds. Default is `3600` seconds (1
hour).

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>lifetimeInSeconds</code></td>

      <td>
        <p><em>Number</em> Expiration of the token in seconds.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setSignResponse(signResponse)`

Whether or not the SAML response should be signed. By default the SAML
assertion will be signed, but not the SAML response. If `true`,
SAML Response will be signed instead of SAML assertion. Default to
`false`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>signResponse</code></td>

      <td>
        <p><em>Boolean</em> Should the SAML response be signed.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setNameIdentifierFormat(nameIdentifierFormat)`

Sets the name ID format. Default is
`urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>nameIdentifierFormat</code></td>

      <td>
        <p><em>String</em> The Name ID Format.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setNameIdentifierProbes(nameIdentifierProbes)`

Auth0 tries to name each of the attributes of this array in order. If one of
them has a value, it will use that for the Subject/NameID. The order is:

1. [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier)
   (mapped from `user_id`)
2. [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress) (mapped
   from `email`)
3. [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) (mapped from
   `name`)

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>nameIdentifierProbes</code></td>

      <td>
        <p>
          <em>String array</em> An array of attributes to try for the name
          identifier.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setAuthnContextClassRef(authnContextClassRef)`

Default is `urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>authnContextClassRef</code></td>

      <td>
        <p><em>String</em> The AuthnContextClassRef.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setSigningCert(signingCert)`

Optionally indicates the public key certificate used to validate SAML
requests. If set, SAML requests will be required to be signed. A sample
value would be
`"-----BEGIN
CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all
the other lines..]-----END CERTIFICATE-----\n"`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>signingCert</code></td>

      <td>
        <p>
          <em>String</em> Optional public key certificate used to validate
          SAML requests.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setIncludeAttributeNameFormat(includeAttributeNameFormat)`

When set to `true`, we infer the NameFormat based on the
attribute name. NameFormat values are
`urn:oasis:names:tc:SAML:2.0:attrname-format:uri`,
`urn:oasis:names:tc:SAML:2.0:attrname-format:basic` and
`urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`.

If set to `false`, the attribute NameFormat is not set in the
assertion. Default is `true`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>includeAttributeNameFormat</code></td>

      <td>
        <p>
          <em>Boolean</em> Should NameFormat be inferred based on the attribute
          name.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setTypedAttributes(typedAttributes)`

When set to `true`, we infer the `xs:type` of the
element. Types are `xs:string`, `xs:boolean`,
`xs:double` and `xs:anyType`. When set to
`false` all `xs:type` are `xs:anyType`.
Default is `true`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>typedAttributes</code></td>

      <td>
        <p><em>Boolean</em>Should <code>xs:type</code> be inferred.</p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setEncryptionCert(encryptionCert)`

Optionally specify a certificate used to encrypt the SAML assertion. The
certificate should be obtained from the service provider. Both the
certificate and public key must be specified. A sample value would be
`"-----BEGIN
CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all
the other lines..]-----END CERTIFICATE-----\n"`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>encryptionCert</code></td>

      <td>
        <p>
          <em>String</em> Optional certificate to encrypt the SAML assertion.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setCert(cert)`

By default, Auth0 will use the private/public key pair assigned to your
tenant to sign SAML responses or assertions. For very specific scenarios,
you might wish to provide your own certificate and private key.

Both the certificate and private key must be specified.

A sample value would be
`"-----BEGIN
CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all
the other lines..]-----END CERTIFICATE-----\n"`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>cert</code></td>

      <td>
        <p>
          <em>String</em>Optional certificate to sign the SAML responses or
          assertions.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setKey(key)`

By default, Auth0 will use the private/public key pair assigned to your
tenant to sign SAML responses or assertions. For very specific scenarios,
you might wish to provide your own certificate and private key.

Since this private key is sensitive, we recommend using the
**Add Secret functionality of Actions**. See here for more details: Write
Your First Action

Both the certificate and private key must be specified.

A sample value would be
`"-----BEGIN PRIVATE
KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all
the other lines..]-----END PRIVATE KEY-----\n"`.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>key</code></td>

      <td>
        <p>
          <em>String</em>Optional private key to sign the SAML responses or
          assertions.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setSignatureAlgorithm(signatureAlgorithm)`

**Deprecated**: Default is `rsa-sha256`

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>signatureAlgorithm</code></td>

      <td>
        <p>
          <code>rsa-sha256</code> | <code>rsa-sha1</code>.
          <code>rsa-sha1</code> should not be used. This is insecure.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.samlResponse.setDigestAlgorithm(digestAlgorithm)`

**Deprecated**: Default is `sha256`

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>digestAlgorithm</code></td>

      <td>
        <p>
          <code>sha256</code> | <code>sha1</code>.
          <code>rsa-sha1</code> should not be used. This is insecure.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.session`

Manage sessions, such as by revoking a user session.

### `api.session.revoke(reason, options)`

Reject the current transaction, revoke the session, and delete associated
refresh tokens. This will prevent the user from completing the flow and no
further Actions are executed.

**Note** This method initiates a session-revoked
[OIDC Back-Channel Logout Initiator](/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators)
to logout users from all applications bound to the current session. Deletion
of session associated refresh tokens is an asynchronous operation.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>reason</code></td>

      <td>
        <p>
          <em>String</em>. A human-readable explanation for rejecting the
          login. This is sent as error\_description to the application that
          initiated the request.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>options</code></td>

      <td>
        <p>
          <em>preserveRefreshTokens</em>. is a boolean used to specify if
          revoke will preserve the refresh tokens bound to the session with
          the same session\_id. Defaults to false.
        </p>

        <p>Example</p>

        ```js lines theme={null}
        api.session.revoke('reason', 
                     {'preserveRefreshTokens':true} );
        ```
      </td>
    </tr>
  </tbody>
</table>

### `api.session.setExpiresAt(absolute)`

Set a new absolute expiration date for a specified session.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>absolute</code></td>

      <td>
        <p>
          <em>Number</em>. The absolute expiry time in milliseconds since the unix epoch.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.session.setIdleExpiresAt(idle)`

Set a new inactivity expiration date for a specified session.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>idle</code></td>

      <td>
        <p><em>Number</em>. The inactivity expiry time in milliseconds since the unix epoch.</p><p>This method sets the session inactivity timeout for the current interaction. If the method is not reapplied, subsequent successful interactions will override the inactivity timeout using the session inactivity timeout settings.</p>
      </td>
    </tr>
  </tbody>
</table>

## `api.transaction [Early Access]`

### `api.transaction.setMetadata(name, value) [Early Access]`

Store or update shared data across custom Actions for the duration of a transaction.\
Transaction metadata allows you to share data between multiple Actions within the same authentication flow. Data stored using this method is available in the `event.transaction.metadata` object in the current and subsequent Actions and persists throughout the entire transaction lifecycle.

They are subject to Transaction Metadata Limits. To learn more, read [Actions Limitations](/docs/customize/actions/limitations) .

**NOTE:** Transaction metadata is only available during the current authentication transaction and is not persisted beyond the completion of the authentication flow. This feature is only currently available on `post-login` Actions.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>key</code></td>

      <td>
        <p>
          <em>String</em>. The key of the metadata property to be set.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p>
          <em>String, Number, Boolean</em>. The value of the metadata property. Set to <code>null</code> removes the property.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.user`

Make application-specific changes to the metadata of the user that is
logging in.

*NOTE: **Invoking these methods does not update the metadata immediately**. You
can call them several times throughout multiple Actions of the same flow,
and the engine will aggregate the changes and **update the metadata at
once before the flow is completed**.*

### `api.user.setAppMetadata(name, value)`

Set application metadata for the user that is logging in. Data stored within
app\_metadata is not editable by the user.

Note: This trigger makes a call to the Management API, consuming the Management API rate limit. If this request hits the rate limit and fails to retry within the timeout window, you will receive a `Deadline Exceeded` error.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>name</code></td>

      <td>
        <p><em>String</em>. The name of metadata property.</p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p>
          <em>Any value</em>. The value of the metadata property. This may be
          set to <code>null</code> to remove the metadata property.
        </p>
      </td>
    </tr>
  </tbody>
</table>

### `api.user.setUserMetadata(name, value)`

Set general metadata for the user that is logging in.

Note: This trigger makes a call to the Management API, consuming the Management API rate limit. If this request hits the rate limit and fails to retry within the timeout window, you will receive a `Deadline Exceeded` error.

Returns a reference to the `api` object.

<table class="table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>name</code></td>

      <td>
        <p><em>String</em>. The name of metadata property.</p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p>
          <em>Any value</em>. The value of the metadata property. This may be
          set to <code>null</code> to remove the metadata property.
        </p>
      </td>
    </tr>
  </tbody>
</table>