Actions Triggers: post-login - API Object

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 will prevent the end-user from completing the login flow. This will NOT cancel other user-related side effects (such as metadata changes) requested by this Action. The login flow will immediately stop following the completion of this action and no further Actions will be executed.

Returns a reference to the api object.

api.accessToken

Request changes to the access token being issued.

api.accessToken.setCustomClaim(name, value)

Set a custom claim on the Access Token that will be issued upon completion of the login flow.

Returns a reference to the api object.

api.accessToken.addScope(scope)

Add a scope on the Access Token that will be issued upon completion of the login flow.

Returns a reference to the api object.

api.accessToken.removeScope(scope)

Remove a scope on the Access Token that will be issued upon completion of the login flow.

Returns a reference to the api object.

api.authentication

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

api.authentication.recordMethod(provider_url)

Indicate that a custom authentication method has been completed in the current session. This method will then be available in the `event.authentication.methods` array in subsequent logins.

Important: This API is only available from within the onContinuePostLogin function for PostLogin Actions. In other words, this may be used to record the completion of a custom authentication method after redirecting the user via api.redirect.sendUserTo().

Returns a reference to the api object.

api.authentication.challengeWith(factor, options)

Challenge the user with one or more specified multifactor authentication factors. This method presents the default challenge first, then allows the user to select a different option if additional factors have been supplied. If the user has not enrolled in any of the factors supplied (including both the default and any additional factors), the command fails.

Note: This method overrides existing policies and rules that enable or disable MFA in a tenant.

api.authentication.challengeWith({
  type: 'otp'
}, {
  additionalFactors: [{
    type: 'push-notification'
  }, {
    type: 'phone'
  }]
})

api.authentication.challengeWithAny(factors)

Trigger an MFA challenge and allow the user to select their preferred factor from the supplied list. This method presents a factor picker to the user rather than a specific challenge, in accordance with the following conditions:

• If two or more factors are specified, a factor picker displays to the user.
• If the user has only enrolled in one of the specified factors (or only one factor is specified), the factor picker is skipped.
• If the user has not enrolled in any of the specified factors, the challenge command fails.

Note: This method overrides existing policies and rules that enable or disable MFA in a tenant.

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 will have a code property that indicates the nature of the failure.

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 with a value property holding the cached value as well as an expires_at property indicating 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.

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 will have lifetimes of up to the specified ttl or expires_at values. If no lifetime is specified, a default of lifetime of 15 minutes will be used. Lifetimes may not exceed the maximum duration listed at Actions Cache Limits.

api.idToken

Request changes to the ID token being issued.

api.idToken.setCustomClaim(name, value)

Set a custom claim on the ID token that will be issued upon completion of the login flow.

Returns a reference to the api object.

api.multifactor

Set the requirement for multifactor authentication on the login attempt.

api.multifactor.enable(provider, options)

Enable multifactor authentication for this login flow. When enabled, users must complete the configured multifactor challenge. The actual multifactor challenge will be deferred to the end of the login flow.

Returns a reference to the api object.

api.user

Make application-specific changes to the metadata of the user that is logging in.

NOTE: Invoking these methods won't update the metadata immediately. You can call them several times throughout multiple actions of the same flow and the engine will aggregate the changes and update the metadata at once before the flow is completed.

api.user.setAppMetadata(name, value)

Set application metadata for the user that is logging in. Data stored within app_metadata is not editable by the user.

Returns a reference to the api object.

api.user.setUserMetadata(name, value)

Set general metadata for the user that is logging in.

Returns a reference to the api object.

api.redirect

api.samlResponse

Modify the SAML Response for the user that is logging in.

api.samlResponse.setAttribute(attribute, value)

Set a custom SAML attribute.

A failed operation throws an Error. For errors, the returned object has a message that indicates the nature of the failure.

The value must be of type SAMLValue, which can be string | number | boolean | null | Array < string | number | boolean >

api.samlResponse.setAudience(audience)

Alter the audience of the SAML Response. Default is the issuer on SAMLRequest.

api.samlResponse.setRecipient(recipient)

Alter the recipient of the SAML assertion (SubjectConfirmationData). Default is AssertionConsumerUrl on SAMLRequest or callback URL if no SAMLRequest was sent.