Docs

createUser()

Creates a User. Your user management settings determine how you should setup your user model.

Any email address and phone number created using this method will be automatically marked as verified.

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

  • Name
    firstName?
    Type
    string
    Description

    The user's first name.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name.

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

createUser() 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_2cSSCzV7948rhPJMsY601tXsEU4',
  passwordEnabled: true,
  totpEnabled: false,
  backupCodeEnabled: false,
  twoFactorEnabled: false,
  banned: false,
  createdAt: 1708103362688,
  updatedAt: 1708103362701,
  imageUrl: 'https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18yVjdKRFdyclJwRmZFZTlqQUM2dWpSMG8xSlQiLCJyaWQiOiJ1c2VyXzJjU1NDelY3OTQ4cmhQSk1zWTYwMXRYc0VVNCIsImluaXRpYWxzIjoiVFUifQ',
  hasImage: false,
  primaryEmailAddressId: 'idn_2cSSCuFhU35F5u5Labwtmj7xU6B',
  primaryPhoneNumberId: null,
  primaryWeb3WalletId: null,
  lastSignInAt: null,
  externalId: null,
  username: null,
  firstName: 'Test',
  lastName: 'User',
  publicMetadata: {},
  privateMetadata: {},
  unsafeMetadata: {},
  emailAddresses: [
    _EmailAddress {
      id: 'idn_2cSSCuFhU35F5u5Labwtmj7xU6B',
      emailAddress: 'testclerk123@gmail.com',
      verification: [_Verification],
      linkedTo: []
    }
  ],
  phoneNumbers: [],
  web3Wallets: [],
  externalAccounts: [],
  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.

Feedback

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