> ## Documentation Index > Fetch the complete documentation index at: https://auth0.com/llms.txt > Use this file to discover all available pages before exploring further. # How to Set Custom User IDs with Actions for New Users in Database Connections > Write a `pre-user-registration` Action to set custom `user_id`s when creating new users in database connections so you can maintain ID consistency across systems or standardize ID formats. > [!WARNING] > > **The custom user ID assignment with Actions feature is in .** By default, when creating a new user, Auth0 automatically generates a [`user_id` attribute](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure#param-identities) as a unique identifier of that user. Database connections support setting a custom user ID during user creation. You may want to specify your own user IDs if you need standardized formatting or consistency across systems. For example: * Maintaining an existing user ID structure when migrating from another identity provider to Auth0 so that tokens, audit logs, and integrations remain consistent. * Ensuring compatibility with data or billing systems that require a specific formats like UUID v4 or sequential integer user IDs. * Matching user IDs to primary keys in an internal database or CRM for simplified data joins and reporting. * Composing deterministic user IDs from known attributes, like tenant names or app metadata. You can set a custom `user_id` by calling `api.user.setUserId()` in an [Action](https://auth0.com/docs/customize/actions/actions-overview.md) added to the [`pre-user-registration` trigger](https://auth0.com/docs/customize/actions/explore-triggers/pre-user-registration), which fires before a new user profile is created. ## How user IDs are determined In the user profile, [the `identities` array](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure#param-identities) contains objects with information from each identity provider with which the user authenticates. Setting a custom user ID sets the `user_id` attribute in the `identities` array object for the database connection. There are different ways to set a custom `identities` user ID depending on how you create the user. The following table summarizes available creation methods and how the `user_id` is set by precedence: | User creation method | `user_id` precedence | | - | - | | The [Authentication API's Create a new user endpoint](https://auth0.com/docs/api/authentication/signup/create-a-new-user.md) (`POST /dbconnections/signup`) or [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) sign-up |
  1. `api.user.setUserId()` in a `pre-user-registration` Action
  2. Auth0-generated user ID
| | The [Management API's Create a user endpoint](https://auth0.com/docs/api/management/v2/users/post-users.md) (`POST /users`) |
  1. `api.user.setUserId()` in a `pre-user-registration` Action
  2. [`user_id` set in the request body](https://auth0.com/docs/api/management/v2/users/post-users#body-user-id)
  3. Auth0-generated user ID
| | A custom database connection with [automatic migration](https://auth0.com/docs/manage-users/user-migration/configure-automatic-migration-from-your-database.md) enabled |
  1. `api.user.setUserId()` in a `pre-user-registration` Action
  2. The [`user_id` attribute in the normalized user profile](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure#param-user-id) returned from the [Login](https://auth0.com/docs/authenticate/database-connections/custom-db/templates/login.md) and [Get User](https://auth0.com/docs/authenticate/database-connections/custom-db/templates/get-user.md) database action scripts
  3. Auth0-generated user ID
| | A [bulk user import job](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports.md) |
  1. The [bulk import JSON's `user_id` property](https://auth0.com/docs/manage-users/user-migration/bulk-user-import-schema#param-user-id)
  2. Auth0-generated user ID
| In summary, a user ID set with `api.user.setUserId()` in a `pre-user-registration` Action takes precedence over other methods of setting a custom user ID, but the `pre-user-registration` trigger does not fire for bulk import jobs. Additionally, Auth0 sets the user profile's [root-level `user_id`](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure#param-user-id) based on the profile's primary identity, which is the first identity in the `identities` array. The root-level `user_id` is the primary identity's user ID prefixed with the connection strategy (for example, `auth0|your_custom_id`). The root-level `user_id` is used as the value for the [`sub` claim](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-claims), for example, so make sure downstream systems expect the prefixed value. ## Set custom user IDs with a `pre-user-registration` Action To set a custom `user_id` with a `pre-user-registration` Action, you need to create the Action, write the code that sets the user ID to the value you want, and then add the Action to the `pre-user-registration` trigger. ### 1. Create the Action Go to **[Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library)**. Select **Create Action**, then choose **Create Custom Action** from the drop-down menu. In the **Create Action** window that opens, enter the following fields: * **Name**: Choose a name for your action, like "Set Custom User ID". * **Trigger**: Select **Pre User Registration**. * **Runtime**: Choose your Node runtime. Then select **Create** to go to the Actions code editor for the new Action. ### 2. Write the Action code In the Actions code editor, [write your Action code](https://auth0.com/docs/customize/actions/action-coding-guidelines.md) using `api.user.setUserId()` to set the user ID based on your use case. Custom user IDs must meet the following requirements: * The `user_id` must be unique within the connection. If a user with the specified `user_id` already exists, creation fails. * The `user_id` must pass the same validation as the Management API [Create a user endpoint's `user_id` body parameter](https://auth0.com/docs/api/management/v2/users/post-users#body-user-id). If user creation fails due to user ID issues, check your [tenant logs](https://auth0.com/docs/deploy-monitor/logs.md) for [log type `fs`](https://auth0.com/docs/tenant-logs/auth-signup-fail/fs) (failed sign-up). > **Example: Generate a UUID v4** > > You can generate a UUID v4 using Node's built-in `crypto` module: > > ```js wrap Example: Generate a UUID v4 theme={null} > exports.onExecutePreUserRegistration = async (event, api) => { > const crypto = require('crypto'); > api.user.setUserId(crypto.randomUUID()); > }; > ``` > **Example: Generate a specific UUID version** > > If you need a specific UUID version (v1, v5, v7, etc.), add the `uuid` npm package as a dependency and use it in your Action: > > ```js wrap Example: Generate a specific UUID version theme={null} > const { v7: uuidv7 } = require('uuid'); > > exports.onExecutePreUserRegistration = async (event, api) => { > api.user.setUserId(uuidv7()); > }; > ``` > **Example: Compose an ID from sign-up data** > > You can compose a deterministic user ID from sign-up data, like an `app_metadata` value: > > ```js wrap Example: Compose an ID from sign-up data theme={null} > exports.onExecutePreUserRegistration = async (event, api) => { > const externalId = event.user.app_metadata?.external_id; > if (externalId) { > api.user.setUserId(externalId); > } > }; > ``` Once you finish writing and [testing the Action](https://auth0.com/docs/customize/actions/test-actions.md), select **Deploy**. ### 3. Add the Action to the trigger After you deploy the Action, go to **[Dashboard > Actions > Triggers > Pre User Registration](https://manage.auth0.com/#/actions/triggers/pre-user-registration)**. In the **Add Action** section on the right, under **Custom**, drag the new Action you created into the flow between **Start** and **Complete**. Then, select **Apply**. ## Limitations * Setting a custom user ID with the `pre-user-registration` trigger is not supported for passwordless connections. * The `pre-user-registration` trigger does not fire for bulk import jobs. * You cannot set a custom `user_id` for users logging in via social or enterprise connections because those IDs are provided by the external identity provider. * You cannot change an existing user's `user_id`.