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

> Learn about the password reset post-challenge Action trigger's API object.

# Actions Triggers: post-challenge - API Object

The API object for the `post-challenge` 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 prevents the end-user
from completing the login flow. This does  **not**  cancel other user-related side effects requested by this Action, such as metadata changes. The login flow immediately stops 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 may be presented directly in end-user interfaces.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.authentication`

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

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

Request a challenge for multifactor authentication using the supplied factor and optional additional factors.

When a multifactor challenge is requested, subsequent Actions will not run until that challenge is fulfilled by the user. A user can satisfy this challenge by:

* Having already completed a challenge for a matching factor in this transaction.
* Successfully completing the challenge for the default factor.
* Successfully completing the challenge for any of the optional factors described in `additionalFactors`.

**Note:** If the user has not already satisfied the requirements of the challenge, they are presented with a factor challenge screen. If `additionalFactors` are supplied, the user can choose to authenticate with a different factor than the default challenge.

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

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

      <td>
        <p>
          <em>FactorSelector</em>. An object describing the type of factor (and its options) that should be used for the initial challenge.
        </p>
      </td>
    </tr>

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

      <td>
        <p>
          Optional Object. Additional options that can also specify <code>additionalFactors</code> as a property.
        </p>
      </td>
    </tr>
  </tbody>
</table>

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

Request a challenge for multifactor authentication using any of the supplied factors or optional additional factors.

When a multifactor challenge is requested, subsequent Actions will not run until that challenge is fulfilled by the user. A user can satisfy this challenge by:

* Having already completed a challenge for a matching factor in this transaction.
* Successfully completing the challenge for the default factor.

**Note:** If the user has not already satisfied the requirements of the challenge, they are presented with a factor challenge screen. If there is a specific preferred factor, the `api.authentication.challengeWith()` method is preferred.

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

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

      <td>
        <p>
          <em>FactorSelector\[]</em>. An array of factors.
        </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 includes 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 containing the following properties:

* `value` The cached value
* `expires_at` 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 can have lifetimes of up to the specified
`ttl` or `expires_at` values. If no lifetime is
specified, a default of lifetime of 15 minutes is used. Lifetimes cannot exceed the maximum duration listed in the
[Actions Cache Limits](/docs/customize/actions/limitations).

<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>
          <strong>Note:</strong> This value should not be supplied if <code>ttl</code> value is provided. If values are supplied for both options, the earlier expiry of the two is 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>
          <strong>Note:</strong> This value should not be supplied if a  <code>expires\_at</code> value is provided. If values are supplied for both options, the earlier expiry of the two is used.
        </p>
      </td>
    </tr>
  </tbody>
</table>

## `api.redirect`

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

Create a session token that is suitable for use as a query string parameter redirect target (via `sendUserTo`) and 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 the token expires. Default is 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 shared with the redirect target. This 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 the
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 target URL of the redirect.</p>
      </td>
    </tr>

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

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

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

      <td>
        <p>
          <em>Options</em>. Additional query string parameters to append 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 simultaneously 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.transaction`

### `api.transaction.setResultUrl(url, options)`

Trigger a browser redirect to the target `url` after the user resets their password.

<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 a user is directed to after updating their password. Ensure this URL is validated and safe for end users.
        </p>
      </td>
    </tr>

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

      <td>
        <p>
          <em>Options</em>. An object representing any additional query string parameters appended to the target URL.
        </p>
      </td>
    </tr>

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

      <td>
        <p>
          <em>Options</em>. Additional query string parameters to append to the target URL.
        </p>
      </td>
    </tr>
  </tbody>
</table>