Docs

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>

CreateUserParams

  • 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_hasher property.

  • Name
    passwordHasher?
    Type
    'argon2i' | 'argon2id' | 'awscognito' | '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. The algorithms we support at the moment are:

    Warning

    For password hashers considered insecure (currently, MD5 and SHA256), the corresponding user password hashes will be transparently migrated to bcrypt (a secure hasher) upon the user's first successful password sign in. Insecure schemes are marked with (insecure) in the list below.

    • awscognito
      • When set, password_digest must be in the format of awscognito#<userpoolid>#<clientid>#<identifier>.
      • Upon a successful migration, password_hasher will be updated to bcrypt, and password_digest will be updated to a bcrypt hash.
      • See the migration guide for usage details.
    • bcrypt
      • When set, password_digest must be in the format of $<algorithm version>$<cost>$<salt & hash>
    • bcrypt_sha256_django
      • This is the Django-specific variant of Bcrypt, using SHA256 hashing function. When set, password_digest must be in the format of (as exported from Django): bcrypt_sha256$$<algorithm version>$<cost>$<salt & hash>
    • bcrypt_peppered
      • Used in implementations such as Devise for Ruby on Rails applications. Identical to bcrypt except that a pepper string is appended to the input before hashing. When set, password_digest must be in the format of $<algorithm version>$<cost>$<salt & hash>$<pepper>
    • md5 (insecure)
      • When set, password_digest must be in the format of 5f4dcc3b5aa765d61d8327deb882cf99
    • pbkdf2_sha1
      • When set, password_digest must be in the format of pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string> or pbkdf2_sha1$<iterations>$<salt-as-hex-string>$<hash-as-hex-string>$<key-length>
      • Accepts the salt as a hex-encoded string. If the salt is not a valid hex string, the raw bytes will be used instead. Accepts the hash as a hex-encoded string. Optionally accepts the key length as the last parameter (defaults to 32).
    • pbkdf2_sha256
      • This is the PBKDF2 algorithm using the SHA256 hashing function. When set, password_digest must be in the format of pbkdf2_sha256$<iterations>$<salt>$<hash>
      • Both the salt and the hash are expected to be base64-encoded.
    • pbkdf2_sha512
      • This is the PBKDF2 algorithm using the SHA512 hashing function. When set, password_digest must be in the format of pbkdf2_sha512$<iterations>$<salt>$<hash>
    • pbkdf2_sha256_django
      • This is the Django-specific variant of PBKDF2. When set, password_digest must be in the format of (as exported from Django): pbkdf2_sha256$<iterations>$<salt>$<hash>
      • The salt is expected to be un-encoded, the hash is expected base64-encoded.
    • phpass
      • Portable public domain password hashing framework for use in PHP applications. When set, password_digest must be in the format of $P$<rounds><salt><encoded-checksum>
      • $P$ is the prefix used to identify phpass hashes.
      • rounds is a single character encoding a 6-bit integer representing the number of rounds used.
      • salt is eight characters drawn from [./0-9A-Za-z], providing a 48-bit salt.
      • checksum is 22 characters drawn from the same set, encoding the 128-bit checksum with MD5.
    • scrypt_firebase
      • The Firebase-specific variant of scrypt. When set, password_digest must be in the format of <hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>
      • hash: The actual Base64 hash. This can be retrieved when exporting the user from Firebase.
      • salt: The salt used to generate the above hash. Again, this is given when exporting the user from Firebase.
      • signer key: The base64 encoded signer key.
      • salt separator: The base64 encoded salt separator.
      • rounds: The number of rounds the algorithm needs to run.
      • memory cost: The cost of the algorithm run
      • The first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase. The other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters.
    • scrypt_werkzeug
      • The Werkzeug-specific variant of scrypt. When set, password_digest must be in the format of $<algorithm args>$<salt>$<hash>
      • algorithm args: The algorithm used to generate the hash.
      • salt: The salt used to generate the above hash.
      • hash: The actual Base64 hash.
    • sha256 (insecure)
      • When set, password_digest must be a 64-length hex string. For example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
    • argon2 variants: argon2i and argon2id.
      • Algorithms in the argon2 family generate digests that encode the following information:
        • version (v): The argon version, version 19 is assumed
        • memory (m): The memory used by the algorithm (in kibibytes)
        • iterations (t): The number of iterations to perform
        • parallelism (p): The number of threads to use
      • Parts are demarcated by the $ character, with the first part identifying the algorithm variant The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism). The final part is the actual digest.
      • When set, password_digest must be in the format of $argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc
      • For the argon2id case, the value of the algorithm in the first part of the digest is argon2id: $argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU

    If you need support for any particular hashing algorithm, contact support.

  • 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. 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. 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,
  locked: 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 information.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on