API Object

Learn about the pre-user-registration Action trigger’s API object.

The API object for the pre-user-registration Actions trigger exposes methods for controlling access, managing user metadata, caching data, and signaling validation errors.

api.access

Modify the access of the user that is attempting to register, such as rejecting the signup attempt.

api.access.deny(reason, userMessage) · void

Deny the user from being able to register. The signup flow will immediately stop following the completion of this action and no further Actions will be executed.

Example

exports.onExecutePreUserRegistration = async (event, api) => {
  api.access.deny('user_blocked', 'Registration is not allowed at this time.');
};

Parameters

Show Parameters

reason · string

An internal reason describing why this registration attempt is being denied. This value will appear in tenant logs.

userMessage · string

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

api.user

Make changes to the metadata of the user that is registering.

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

Set application-specific metadata for the user that is registering.

Note: This method should not be used in callbacks. Invoking this method won’t update the metadata immediately. You can call this 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.

Example

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

Parameters

Show Parameters

key · string

The metadata property to be set.

value · unknown

The value of the metadata property. This may be set to null to remove the metadata property.

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

Set general metadata for the user that is registering.

Note: This method should not be used in callbacks. Invoking this method won’t update the metadata immediately. You can call this 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.

Example

exports.onExecutePreUserRegistration = async (event, api) => {
  api.user.setUserMetadata('preferences', { theme: 'dark' });
};

Parameters

Show Parameters

key · string

The metadata property to be set.

value · unknown

The value of the metadata property. This may be set to null to remove the metadata property.

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

api.validation

Signal validation errors to prevent the user from registering.

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

Deny the user from being able to register. The signup flow will immediately stop following the completion of this action and no further Actions will be executed.

Example

exports.onExecutePreUserRegistration = async (event, api) => {
  api.validation.error('invalid_email_domain', 'Email domain is not allowed.');
};

Parameters

Show Parameters

errorCode · string

A customer-defined error code describing why this registration attempt is being denied. This value will appear in tenant logs.

errorMessage · string

A customer-defined explanation for rejecting the registration attempt. This may be presented directly in end-user interfaces.