API Object

Learn about the post-login Action trigger’s API object.

The API object for the post-login Actions trigger exposes methods for controlling access, customizing tokens, managing authentication state, configuring redirects, and more.

api.access

Modify the access of the user that is logging in, such as rejecting the login attempt.

api.access.deny(reason) · void

Mark the current login attempt as denied. This prevents 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.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.access.deny('You are not allowed to log in.');
};

Parameters

Show Parameters

reason · string

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

api.accessToken

Request changes to the access token being issued.

api.accessToken.setCustomClaim(key, value) · void

Set a custom claim on the access token issued upon completion of the login flow.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.accessToken.setCustomClaim('https://example.com/role', 'admin');
};

Parameters

Show Parameters

key · string

Name of the claim (note that this may need to be a fully-qualified URL).

value · unknown

The value of the claim.

api.accessToken.addScope(scope) · void

Add a scope to the access token issued upon completion of the login flow.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.accessToken.addScope('read:reports');
};

Parameters

Show Parameters

scope · string

The scope to be added.

api.accessToken.removeScope(scope) · void

Remove a scope from the access token issued upon completion of the login flow.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.accessToken.removeScope('admin:full');
};

Parameters

Show Parameters

scope · string

The scope to be removed.

api.idToken

Request changes to the ID token being issued.

api.idToken.setCustomClaim(key, value) · void

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

Example

exports.onExecutePostLogin = async (event, api) => {
  api.idToken.setCustomClaim('https://example.com/department', 'engineering');
};

Parameters

Show Parameters

key · string

Name of the claim (note that this may need to be a fully-qualified URL).

value · unknown

The value of the claim.

api.authentication

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

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

Request a challenge for MFA using the supplied factor. Subsequent Actions will not run until the challenge is fulfilled.

Challenge with a specific factor

api.authentication.challengeWith({ type: 'phone', options: { preferredMethod: 'both' } });

Challenge with additional factors

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

Parameters

Show Parameters

factor · object

The factor to use for the initial challenge.

Show factor properties

type · string

The factor type. Allowed values: otp, email, webauthn-platform, webauthn-roaming, recovery-code, push-notification, phone.

options · object

Additional options for the factor type. Optional.

options · object

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.

Example

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

Parameters

Show Parameters

factors · array of objects

An array of factors.

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

Request an enrollment for MFA using the supplied factor.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.authentication.enrollWith({ type: 'otp' }, {
    additionalFactors: [{ type: 'push-notification' }]
  });
};

Parameters

Show Parameters

factor · object

The factor to use for enrollment.

Show factor properties

type · string

The factor type. Allowed values: otp, webauthn-platform, webauthn-roaming, recovery-code, push, push-notification.

options · object

Additional options for the factor type. Optional.

options · object

Optional.

Show options properties

additionalFactors · array of objects

Additional factors the user may choose from.

api.authentication.recordMethod(provider_url) · void

Indicate that a custom authentication method has been completed. Only available from within onContinuePostLogin after a redirect.

Example

exports.onContinuePostLogin = async (event, api) => {
  api.authentication.recordMethod('https://my-app.example.com/mfa');
};

Parameters

Show Parameters

provider_url · string

An http: or https: URL that uniquely represents the completed authentication method.

api.authentication.setPrimaryUser(primary_user_id) · void

Change the primary user for the login transaction. Use in account-linking scenarios where the initiating identity is now a secondary identity of an existing user.

IMPORTANT: Insecurely linking accounts can allow malicious actors to access legitimate user accounts. The identity used to authenticate must be among the secondary identities of the referenced user.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.authentication.setPrimaryUser('auth0|existing_user_id');
};

Parameters

Show Parameters

primary_user_id · string

The user ID of the user for whom tokens should be issued (the sub claim).

api.multifactor

Set or remove the requirement for MFA on the login attempt.

api.multifactor.enable(provider, options) · void

Enable MFA for this login flow. Users must complete the configured MFA challenge before completing login.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.multifactor.enable('any', { allowRememberBrowser: true });
};

Parameters

Show Parameters

provider · string

The MFA provider to use or "any" to use any configured provider. Allowed values: duo, none, guardian, google-authenticator, any.

options · object

Optional.

Show options properties

allowRememberBrowser · boolean

When google-authenticator or duo, prompts MFA once every 30 days. When guardian, shows enrollment checkbox. Defaults to false.

providerOptions · object

Additional options for the duo provider only. Optional.

api.redirect

Configure and initiate external redirects.

api.redirect.encodeToken(options) · string

Create a signed session token for use as a query string parameter in a redirect. The target endpoint verifies authenticity using a shared secret.

Example

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

Parameters

Show Parameters

options · object

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.onExecutePostLogin = 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 passed to the /continue endpoint.

Example

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

Parameters

Show Parameters

options · object

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.user

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

api.user.setAppMetadata(key, value) · void

Set application-specific metadata for the user. This function works only with metadata in object format.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.user.setAppMetadata('plan', 'enterprise');
};

Parameters

Show Parameters

key · string

The metadata property to be set.

value · unknown

The value of the metadata property. Set to null to remove the property.

api.user.setUserMetadata(key, value) · void

Set general metadata for the user that is logging in. This function works only with metadata in object format.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.user.setUserMetadata('last_login_ip', event.request.ip);
};

Parameters

Show Parameters

key · string

The metadata property to be set.

value · unknown

The value of the metadata property. Set to null to remove the property.

api.session

Request changes to the current user’s session.

api.session.revoke(reason, options) · void

[Enterprise] Revoke the current user session and mark the login attempt as denied.

Revoke the session while preserving refresh tokens

api.session.revoke('reason', { preserveRefreshTokens: true });

Parameters

Show Parameters

reason · string

A human-readable explanation for rejecting the login.

options · object

Optional.

Show options properties

preserveRefreshTokens · boolean

If true, ends the session but keeps refresh tokens. Defaults to false.

api.session.setExpiresAt(absolute) · void

[Enterprise] Sets a new absolute expiration time for the current session.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.session.setExpiresAt(Date.now() + 8 * 60 * 60 * 1000); // 8 hours
};

Parameters

Show Parameters

absolute · number

The new absolute expiration time in milliseconds since the unix epoch.

api.session.setMetadata(key, value) · void

[Enterprise] Sets a key-value pair in the metadata object of the current session.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.session.setMetadata('login_method', 'sso');
};

Parameters

Show Parameters

key · string

The key to set in the metadata object.

value · string

The value to set. Null values delete the key.

api.refreshToken

Request changes to the current user’s refresh token.

api.refreshToken.revoke(reason) · void

[Enterprise] Revoke the current refresh token and deny the refresh token exchange.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.refreshToken.revoke('Token has been invalidated.');
};

Parameters

Show Parameters

reason · string

A human-readable explanation for rejecting the refresh token exchange.

api.refreshToken.setMetadata(key, value) · void

[Enterprise] Sets a key-value pair in the metadata object of the current refresh token.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.refreshToken.setMetadata('issued_for', 'mobile_app');
};

Parameters

Show Parameters

key · string

The key to set in the metadata object.

value · string

The value to set. Null values delete the key.

api.validation

Prevent user from logging in by signaling a validation error.

api.validation.error(errorCode, errorMessage) · void

Throw a validation error to prevent login.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.validation.error('access_denied', 'User is not allowed to log in.');
};

Parameters

Show Parameters

errorCode · string

A customer-defined error code for the validation error.

errorMessage · string

A customer-defined message for the validation error.

api.prompt

Render a custom prompt screen.

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

Render a custom prompt during the login flow.

Example

exports.onExecutePostLogin = 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.samlResponse

Configure custom SAML response attributes.

api.samlResponse.setAttribute(attribute, value) · void

Set attributes on the SAML assertion issued to the authenticated user.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.samlResponse.setAttribute('http://schemas.example.com/role', 'admin');
};

Parameters

Show Parameters

attribute · string

The SAML attribute to set.

value · unknown

The value of the SAML claim. Set to null or undefined to remove the claim.

api.samlResponse.setAudience(audience) · void

Set the audience of the SAML assertion. Default is the issuer on SAMLRequest.

Example

exports.onExecutePostLogin = async (event, api) => {
  api.samlResponse.setAudience('https://sp.example.com');
};

Parameters

Show Parameters

audience · string

The audience value.

api.samlResponse.setEncryptionAlgorithm(encryptionAlgorithm) · void

Set the encryption algorithm for the SAML assertion. Default is aes256-cbc.

Set the encryption algorithm to aes256-gcm (recommended)

api.samlResponse.setEncryptionAlgorithm('aes256-gcm');

Parameters

Show Parameters

encryptionAlgorithm · string

The algorithm to use. Allowed values: aes256-gcm.

api.groups

Get information about user group membership.

api.groups.getUserGroups(params) · Promise<object>

Get the paginated list of groups the user belongs to.

Example

exports.onExecutePostLogin = async (event, api) => {
  const groups = await api.groups.getUserGroups({ take: 10 });
};

Parameters

Show Parameters

params · object

Pagination options. Optional.

Show params properties

take · number

Number of results to return. Optional.

from · string

Cursor for pagination. Optional.

api.groups.hasGroupMembership(groups) · Promise<object>

Check if the user is a member of any of the specified groups.

Example

exports.onExecutePostLogin = async (event, api) => {
  const result = await api.groups.hasGroupMembership(['admins', 'editors']);
};

Parameters

Show Parameters

groups · array of strings

An array of group identifiers (IDs or names) to check membership against.

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.onExecutePostLogin = 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.onExecutePostLogin = 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.onExecutePostLogin = 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.