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.

Parameter	Description
reason	String. A human-readable explanation for rejecting the login. 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])

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.

Parameter	Description
factor	FactorSelector. An object describing the type of factor (and its options) that should be used for the initial challenge.
options	Optional Object. Additional options that can also specify additionalFactors as a property.

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.

Parameter	Description
factor	FactorSelector[]. An array of factors.

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.

Parameter	Description
key	String. The key of the record stored in the cache.

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.

Parameter	Description
key	String. The key of the record stored in the cache.

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.

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.

Parameter	Description
key	String. The key of the record stored in the cache.
value	String. The value of the record to be stored.
options	Optional object. Options for adjusting cache behavior.
options.expires_at	Optional number. 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 expires_at. Note: This value should not be supplied if ttl value is provided. If values are supplied for both options, the earlier expiry of the two is used.
options.ttl	Optional number. 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 ttl. Note: This value should not be supplied if a expires_at value is provided. If values are supplied for both options, the earlier expiry of the two is used.

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.

Parameter	Description
options	Options. Configure how sensitive data is encoded into the query parameters of the resulting url.
options.expiresInSeconds	Number. Number of seconds before the token expires. Default is 900.
options.payload	Options. The data intended to be passed to the target of the redirect and whose authenticity and integrity must be provable.
options.secret	String. 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 event.secrets[‘SECRET_NAME’].

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.

Parameter	Description
url	String. The target URL of the redirect.
options	Options. An object representing any additional query string parameters appended to the redirect URL.
options.query	Options. Additional query string parameters to append to the redirect URL.

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.

Parameter	Description
options	Options. Options for retrieving the data encoded in a JWT token passed to the /continue endpoint following a redirect.
options.secret	String. Secret used to encode the token.
options.tokenParameterName	String. The name of the query or body parameter that was sent to the /continue endpoint. Defaults to session_token.

api.transaction

api.transaction.setResultUrl(url, options)

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

Parameter	Description
url	String. The URL a user is directed to after updating their password. Ensure this URL is validated and safe for end users.
options	Options. An object representing any additional query string parameters appended to the target URL.
options.query	Options. Additional query string parameters to append to the target URL.