Create a new user
Creates a new user. Your user management settings determine how you should setup your user model.
By default, any email address and phone number created using this method is marked as verified. Use the email_address_identification_status and phone_number_identification_status arrays to instead create some or all of them as reserved (unverified but usable for sign-in and locked so no other user can claim them).
Note: If you are performing a migration, check out our guide on zero downtime migrations.
The following rate limit rules apply to this endpoint: 1000 requests per 10 seconds for production instances and 100 requests per 10 seconds for development instances
Request body
The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.
The first name to assign to the user
The last name to assign to the user
The locale to assign to the user (e.g., "en-US", "fr-FR")
Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the user's primary email address. Created verified by default; see email_address_identification_status to create them reserved.
Controls the status each email address is created with. Runs parallel to email_address: when provided, it must contain exactly one item per email address, applied by position. When omitted or empty, every email address is created verified. Set an item to reserved to create the corresponding email address reserved instead (unverified but usable for sign-in and locked so no other user can claim it).
Phone numbers to add to the user. Must be unique across your instance. The first phone number will be set as the user's primary phone number. Created verified by default; see phone_number_identification_status to create them reserved.
Controls the status each phone number is created with. Runs parallel to phone_number: when provided, it must contain exactly one item per phone number, applied by position. When omitted or empty, every phone number is created verified. Set an item to reserved to create the corresponding phone number reserved instead (unverified but usable for sign-in and locked so no other user can claim it).
Web3 wallets to add to the user. Must be unique across your instance. The first wallet will be set as the user's primary wallet.
The username to give to the user. It must be unique across your instance.
The plaintext password to give the user. Must be at least 8 characters long, and cannot be in any list of hacked passwords.
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_hasher property.
The hashing algorithm that was used to generate the password digest.
The algorithms we support at the moment are bcrypt, bcrypt_sha256_django, md5, pbkdf2_sha1, pbkdf2_sha256, pbkdf2_sha256_django, pbkdf2_sha512, phpass, md5_phpass, scrypt_firebase, scrypt_werkzeug, sha256, ldap_ssha, the argon2 variants: argon2i and argon2id, sha512_symfony, the SHA-512 variant of the Symfony legacy hasher, and pbkdf2_sha512_hex, a variant of pbkdf2_sha512 that accepts hex-encoded salt and hash.
Each of the supported hashers expects the incoming digest to be in a particular format. See the Clerk docs for more information.
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.
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.
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
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.
Metadata saved on the user, that is visible to both your Frontend and Backend APIs
Metadata saved on the user, that is only visible to your Backend API
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.
If enabled, user can delete themselves via FAPI.
A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).
When set to true all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk.
When set to true, identification types are not enforced. At least one identification type must be enabled and provided on your instance (email, phone, web3 wallet, or username). Users created without required identification types cannot use those authentication strategies It is not recommended to use this flag unless you need to allow Clerk UI components to prompt for required fields while BAPI creates users with minimal data, or for migration a user to Clerk.
If enabled, user can create organizations via FAPI.
The maximum number of organizations the user can create. 0 means unlimited.
A custom date/time denoting when the user signed up to the application, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).
When set to true, the user will bypass client trust checks during sign-in.
When set to true, the user is created already banned and cannot sign in. Requires the same plan support as the ban user endpoint.
When set to true, the user is created already locked. Requires the user lockout feature to be enabled on the instance.
Response
Success
String representing the object's type. Objects of the same type share the same value.
Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled.
Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again.
Unix timestamp of when the user's password was last updated.
Unix timestamp of last sign-in.
Flag to denote whether user is banned or not.
Flag to denote whether user is currently locked, i.e. restricted from signing in or not.
Flag to denote whether user has been deprovisioned and is restricted from signing in.
The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.
The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.
Unix timestamp of last update.
Unix timestamp of creation.
If enabled, user can delete themselves via FAPI.
If enabled, user can create organizations via FAPI.
The maximum number of organizations the user can create. 0 means unlimited.
Unix timestamp of the latest session activity, with day precision.
Unix timestamp of when the user accepted the legal requirements.
When set to true, the user will bypass client trust checks during sign-in.
Example response
{
"last_active_at": 1700690400000,
"legal_accepted_at": 1700690400000
}