> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.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.

# API Object

The API object for the password-reset-post-challenge Actions trigger exposes methods for controlling access, requesting MFA challenges, configuring redirects, rendering prompts, managing the transaction, and caching data.

## `api.access`

Modify the access of the user that is attempting to reset their password.

<ParamField body="api.access.deny(reason)" type="void">
  Mark the current password reset attempt as denied. This will prevent the end-user from completing the password reset flow. The flow will immediately stop following the completion of this action and no further Actions will be executed.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.access.deny('policy_violation', 'Password reset is not allowed at this time.');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="reason" type="string">
      A human-readable explanation for rejecting the password reset. This may be presented directly in end-user interfaces.
    </ParamField>
  </Expandable>
</ParamField>

## `api.authentication`

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

<ParamField body="api.authentication.challengeWith(factor, options)" type="void">
  Request a challenge for multifactor authentication using the supplied factor. The challenge is shown if the user has not already satisfied the requirements.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.authentication.challengeWith({ type: 'otp' });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="factor" type="object">
      An object describing the type of factor to use for the initial challenge.

      <Expandable title="factor properties">
        <ParamField body="type" type="string">
          A type of authentication factor. Allowed values: `otp`, `email`, `webauthn-platform`, `webauthn-roaming`, `recovery-code`.
        </ParamField>

        <ParamField body="options" type="object">
          Additional options for configuring a factor of a given type. Optional.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="options" type="object">
      Additional options including `additionalFactors`. Optional.

      <Expandable title="options properties">
        <ParamField body="additionalFactors" type="array of objects">
          Additional factors the user may choose from.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.authentication.challengeWithAny(factors)" type="void">
  Request a challenge for MFA using any of the supplied factors, showing a factor selection screen first.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.authentication.challengeWithAny([{ type: 'otp' }, { type: 'email' }]);
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="factors" type="array of objects">
      An array of factors the user may choose from.
    </ParamField>
  </Expandable>
</ParamField>

## `api.redirect`

Configure and initiate external redirects.

<ParamField body="api.redirect.encodeToken(options)" type="string">
  Create a signed session token suitable for use as a query string parameter in a redirect. The target endpoint verifies authenticity using a shared secret.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    const token = api.redirect.encodeToken({
      secret: event.secrets.MY_SECRET,
      payload: { userId: event.user.user_id },
    });
    api.redirect.sendUserTo('https://my-app.example.com/verify', { query: { token } });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="options" type="object">
      Configuration for encoding sensitive data into query parameters.

      <Expandable title="options properties">
        <ParamField body="secret" type="string">
          A secret used to sign the JWT. Store as an Action secret and retrieve via `event.secrets['<secret_name>']`.
        </ParamField>

        <ParamField body="payload" type="object">
          The data to pass to the redirect target whose authenticity must be provable.
        </ParamField>

        <ParamField body="expiresInSeconds" type="number">
          Number of seconds before this token expires. Optional.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.redirect.sendUserTo(url, options)" type="void">
  Trigger a browser redirect to the target URL immediately after this action completes.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.redirect.sendUserTo('https://my-app.example.com/verify', {
      query: { user_id: event.user.user_id },
    });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="url" type="string">
      The URL to redirect the user to.
    </ParamField>

    <ParamField body="options" type="object">
      Optional.

      <Expandable title="options properties">
        <ParamField body="query" type="object">
          Additional query string parameters to append to the redirect URL.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.redirect.validateToken(options)" type="object">
  Retrieve and verify data encoded in a JWT token passed to the `/continue` endpoint.

  ```js Example theme={null}
  exports.onContinuePostChallenge = async (event, api) => {
    const payload = api.redirect.validateToken({
      secret: event.secrets.MY_SECRET,
      tokenParameterName: 'token',
    });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="options" type="object">
      Options for retrieving and verifying the token.

      <Expandable title="options properties">
        <ParamField body="secret" type="string">
          The secret used to verify the JWT signature.
        </ParamField>

        <ParamField body="tokenParameterName" type="string">
          The name of the query or body parameter sent to the `/continue` endpoint. Optional.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## `api.prompt`

Render a custom prompt screen.

<ParamField body="api.prompt.render(promptId, promptOptions)" type="void">
  Render a custom prompt during the flow.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.prompt.render('my-custom-prompt', { vars: { name: event.user.name } });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="promptId" type="string">
      The prompt ID.
    </ParamField>

    <ParamField body="promptOptions" type="object">
      The render options. Optional.

      <Expandable title="promptOptions properties">
        <ParamField body="fields" type="object">
          Key-value pairs to populate field values (client-side). Optional.
        </ParamField>

        <ParamField body="vars" type="object">
          Key-value pairs to inject variables (server-side). Optional.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## `api.transaction`

Configure the transaction.

<ParamField body="api.transaction.setResultUrl(url, options)" type="void">
  Set the URL that the user should be redirected to after the password reset.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.transaction.setResultUrl('https://my-app.example.com/password-reset-complete');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="url" type="string">
      The URL to redirect the user to.
    </ParamField>

    <ParamField body="options" type="object">
      Optional.

      <Expandable title="options properties">
        <ParamField body="query" type="object">
          Query parameters to include in the URL.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## `api.cache`

Store and retrieve data that persists across executions.

<ParamField body="api.cache.delete(key)" type="void">
  Delete a cached record at the supplied key if it exists.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.cache.delete('my-key');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the cache record to delete.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.cache.get(key)" type="object | undefined">
  Retrieve a cached record at the supplied key. If found, access the value via `record.value`.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    const record = api.cache.get('my-key');
    if (record) console.log(record.value);
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the record stored in the cache.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.cache.set(key, value, options)" type="void">
  Store or update a string value in the cache at the specified key. Values are scoped to the Trigger and subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations). If no lifetime is specified, a default lifetime of 15 minutes will be used.

  **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 lifetime.

  ```js Example theme={null}
  exports.onExecutePostChallenge = async (event, api) => {
    api.cache.set('my-key', 'my-value', { ttl: 60000 });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the record to be stored.
    </ParamField>

    <ParamField body="value" type="string">
      The value of the record to be stored.
    </ParamField>

    <ParamField body="options" type="CacheSetOptions">
      Options for adjusting cache behavior. Optional.

      <Expandable title="options properties">
        <ParamField body="expires_at" type="number">
          The absolute expiry time in milliseconds since the unix epoch. *Note*: Do not supply if `ttl` is also provided; the earlier expiry will be used.
        </ParamField>

        <ParamField body="ttl" type="number">
          The time-to-live in milliseconds. *Note*: Do not supply if `expires_at` is also provided; the earlier expiry will be used.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>