> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

<ParamField body="api.access.deny(reason, userMessage)" type="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.

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

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="reason" type="string">
      An internal reason describing why this registration attempt is being denied. This value will appear in tenant logs.
    </ParamField>

    <ParamField body="userMessage" type="string">
      A human-readable explanation for rejecting the registration attempt. This may be presented directly in end-user interfaces.
    </ParamField>
  </Expandable>
</ParamField>

## `api.user`

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

<ParamField body="api.user.setAppMetadata(key, value)" type="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.

  ```js Example theme={null}
  exports.onExecutePreUserRegistration = async (event, api) => {
    api.user.setAppMetadata('plan', 'premium');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The metadata property to be set.
    </ParamField>

    <ParamField body="value" type="unknown">
      The value of the metadata property. This may be set to `null` to remove the metadata property.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.user.setUserMetadata(key, value)" type="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.

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

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The metadata property to be set.
    </ParamField>

    <ParamField body="value" type="unknown">
      The value of the metadata property. This may be set to `null` to remove the metadata property.
    </ParamField>
  </Expandable>
</ParamField>

## `api.cache`

Store and retrieve data that persists across executions.

<ParamField body="api.cache.delete(key)" type="void">
  Delete a cached record at the supplied key if it exists.

  ```js Example theme={null}
  exports.onExecutePreUserRegistration = async (event, api) => {
    api.cache.delete('my-key');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the cache record to delete.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.cache.get(key)" type="object | undefined">
  Retrieve a cached record at the supplied key. If found, access the value via `record.value`.

  ```js Example theme={null}
  exports.onExecutePreUserRegistration = async (event, api) => {
    const record = api.cache.get('my-key');
    if (record) console.log(record.value);
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the record stored in the cache.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.cache.set(key, value, options)" type="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](https://auth0.com/docs/customize/actions/limitations). 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.

  ```js Example theme={null}
  exports.onExecutePreUserRegistration = async (event, api) => {
    api.cache.set('my-key', 'my-value', { ttl: 60000 });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the record to be stored.
    </ParamField>

    <ParamField body="value" type="string">
      The value of the record to be stored.
    </ParamField>

    <ParamField body="options" type="CacheSetOptions">
      Options for adjusting cache behavior. Optional.

      <Expandable title="options properties">
        <ParamField body="expires_at" type="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.
        </ParamField>

        <ParamField body="ttl" type="number">
          The time-to-live in milliseconds. *Note*: Do not supply if `expires_at` is also provided; the earlier expiry will be used.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## `api.validation`

Signal validation errors to prevent the user from registering.

<ParamField body="api.validation.error(errorCode, errorMessage)" type="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.

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

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="errorCode" type="string">
      A customer-defined error code describing why this registration attempt is being denied. This value will appear in tenant logs.
    </ParamField>

    <ParamField body="errorMessage" type="string">
      A customer-defined explanation for rejecting the registration attempt. This may be presented directly in end-user interfaces.
    </ParamField>
  </Expandable>
</ParamField>