API Object

Learn about the password-reset-post-challenge Action trigger’s 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.

api.access.deny(reason) · 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.

Example

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

Parameters

Show Parameters

reason · string

A human-readable explanation for rejecting the password reset. This may be presented directly in end-user interfaces.

api.authentication

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

api.authentication.challengeWith(factor, options) · void

Request a challenge for multifactor authentication using the supplied factor. The challenge is shown if the user has not already satisfied the requirements.

Example

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

Parameters

Show Parameters

factor · object

An object describing the type of factor to use for the initial challenge.

Show factor properties

type · string

A type of authentication factor. Allowed values: otp, email, webauthn-platform, webauthn-roaming, recovery-code.

options · object

Additional options for configuring a factor of a given type. Optional.

options · object

Additional options including additionalFactors. Optional.

Show options properties

additionalFactors · array of objects

Additional factors the user may choose from.

api.authentication.challengeWithAny(factors) · void

Request a challenge for MFA using any of the supplied factors, showing a factor selection screen first.

Example

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

Parameters

Show Parameters

factors · array of objects

An array of factors the user may choose from.

api.redirect

Configure and initiate external redirects.

api.redirect.encodeToken(options) · 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.

Example

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

Show Parameters

options · object

Configuration for encoding sensitive data into query parameters.

Show options properties

secret · string

A secret used to sign the JWT. Store as an Action secret and retrieve via event.secrets['<secret_name>'].

payload · object

The data to pass to the redirect target whose authenticity must be provable.

expiresInSeconds · number

Number of seconds before this token expires. Optional.

api.redirect.sendUserTo(url, options) · void

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

Example

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

Parameters

Show Parameters

url · string

The URL to redirect the user to.

options · object

Optional.

Show options properties

query · object

Additional query string parameters to append to the redirect URL.

api.redirect.validateToken(options) · object

Retrieve and verify data encoded in a JWT token passed to the /continue endpoint.

Example

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

Parameters

Show Parameters

options · object

Options for retrieving and verifying the token.

Show options properties

secret · string

The secret used to verify the JWT signature.

tokenParameterName · string

The name of the query or body parameter sent to the /continue endpoint. Optional.

api.prompt

Render a custom prompt screen.

api.prompt.render(promptId, promptOptions) · void

Render a custom prompt during the flow.

Example

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

Parameters

Show Parameters

promptId · string

The prompt ID.

promptOptions · object

The render options. Optional.

Show promptOptions properties

fields · object

Key-value pairs to populate field values (client-side). Optional.

vars · object

Key-value pairs to inject variables (server-side). Optional.

api.transaction

Configure the transaction.

api.transaction.setResultUrl(url, options) · void

Set the URL that the user should be redirected to after the password reset.

Example

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

Parameters

Show Parameters

url · string

The URL to redirect the user to.

options · object

Optional.

Show options properties

query · object

Query parameters to include in the URL.

api.cache

Store and retrieve data that persists across executions.

api.cache.delete(key) · void

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

Example

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

Parameters

Show Parameters

key · string

The key of the cache record to delete.

api.cache.get(key) · object | undefined

Retrieve a cached record at the supplied key. If found, access the value via record.value.

Example

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

Parameters

Show Parameters

key · string

The key of the record stored in the cache.

api.cache.set(key, value, options) · 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. 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.

Example

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

Parameters

Show Parameters

key · string

The key of the record to be stored.

value · string

The value of the record to be stored.

options · CacheSetOptions

Options for adjusting cache behavior. Optional.

Show options properties

expires_at · 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.

ttl · number

The time-to-live in milliseconds. Note: Do not supply if expires_at is also provided; the earlier expiry will be used.