createUser()
Creates a User.
Your user management settings in the Clerk Dashboard determine how you should setup your user model. Anything Required in Users & Authentication -> Email, Phone, Username will need to be provided when creating a user. Trying to add a field that isn't enabled in Users & Authentication -> Email, Phone, Username will result in an error.
Any email address and phone number created using this method will be automatically marked as verified.
A rate limit rule of 20 requests per 10 seconds is applied to this endpoint.
function createUser: (params: CreateUserParams) => Promise<User>;- Name
externalId?- Type
string- Description
The ID of the user you use in your external systems. Must be unique across your instance.
- Name
firstName?- Type
string- Description
The user's first name.
- Name
lastName?- Type
string- Description
The user's last name.
- Name
emailAddress[]?- Type
string[]- Description
Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the users primary email address.
- Name
phoneNumber[]?- Type
string[]- Description
Phone numbers that will be added to the user. Must be unique across your instance. The first phone number will be set as the users primary phone number.
- Name
web3_wallet[]?- Type
string[]- Description
Web3 wallet addresses that will be added to the user. Must be unique across your instance. The first wallet will be set as the users primary wallet.
- Name
username?- Type
string- Description
The username to give to the user. Must be unique across your instance.
- Name
password?- Type
string- Description
The plaintext password to give the user. Must be at least 8 characters long, and can not be in any list of hacked passwords.
- Name
passwordDigest?- Type
string- Description
In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. The digests should be generated with one of the supported algorithms. The hashing algorithm can be specified using the
password_hasherproperty.
- Name
passwordHasher?- Type
'argon2i' | 'argon2id' | 'bcrypt' | 'bcrypt_sha256_django' | 'md5' | 'pbkdf2_sha256' | 'pbkdf2_sha256_django' | 'pbkdf2_sha1' | 'phpass' | 'scrypt_firebase' | 'scrypt_werkzeug' | 'sha256'- Description
The hashing algorithm that was used to generate the password digest. Each of the supported hashers expects the incoming digest to be in a particular format. See the Clerk Backend API reference for more information.
- Name
skipPasswordChecks?- Type
boolean- Description
When set to
true, all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password.
- Name
skipPasswordRequirement?- Type
boolean- Description
When set to
true, password is not required anymore when creating the user and can be omitted. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. Please note that you cannot use this flag if password is the only way for a user to sign into your instance.
- Name
totpSecret?- Type
string- Description
In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. Please note that currently the supported options are:
- Period: 30 seconds
- Code length: 6 digits
- Algorithm: SHA1
- Name
backupCodes?- Type
string[]- Description
If backup codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest.
- Name
publicMetadata?- Type
Record<string, unknown>- Description
Metadata saved on the user, that is visible to both your Frontend and Backend APIs.
- Name
privateMetadata?- Type
Record<string, unknown>- Description
Metadata saved on the user that is only visible to your Backend API.
- Name
unsafeMetadata?- Type
Record<string, unknown>- Description
Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
- Name
createdAt- Type
string- Description
A custom date/time denoting when the user signed up to the application, specified in RFC3339 format. For example:
2012-10-20T07:15:20.902Z.
Example
In this example, the application's instance settings have been configured to use email and password as the primary authentication method.
You can see that the returned response is the created User object, with firstName as "Test", lastName as "User", and emailAddress as an array of email addresses, which includes 'testclerk123@gmail.com'.
const response = await clerkClient.users.createUser({
firstName: "Test",
lastName: "User",
emailAddress: [ "testclerk123@gmail.com" ],
password: "password"
})
console.log(response);
/*
_User {
id: 'user_123',
passwordEnabled: true,
totpEnabled: false,
backupCodeEnabled: false,
twoFactorEnabled: false,
banned: false,
createdAt: 1720041242964,
updatedAt: 1720041242978,
imageUrl: 'https://img.clerk.com/eyJ...',
hasImage: false,
primaryEmailAddressId: 'idn_123',
primaryPhoneNumberId: null,
primaryWeb3WalletId: null,
lastSignInAt: null,
externalId: null,
username: null,
firstName: 'Test',
lastName: 'User',
publicMetadata: {},
privateMetadata: {},
unsafeMetadata: {},
emailAddresses: [
_EmailAddress {
id: 'idn_123',
emailAddress: 'testclerk123@gmail.com',
verification: [_Verification],
linkedTo: []
}
],
phoneNumbers: [],
web3Wallets: [],
externalAccounts: [],
samlAccounts: [],
lastActiveAt: null,
createOrganizationEnabled: true
}
*/Backend API (BAPI) endpoint
This method in the SDK is a wrapper around the BAPI endpoint POST/users. See the BAPI reference for more details.