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.