Programmatic user provisioning
Provision an account from an administrator or server-side workflow.
Clerk · Module
users.createUser
Creates a Clerk User through the Backend SDK or its underlying POST/users endpoint. Required attributes and permitted fields come from the instance's Clerk Dashboard configuration.
How it works
Call the Backend SDK method with a CreateUserParams object. Clerk checks the instance's required user settings, creates the account, and returns the resulting User; email addresses and phone numbers are verified automatically unless their identification status is set to reserved.
Syntax
function createUser(params: CreateUserParams): Promise<User>Parameters
| Name | Type | Description |
|---|---|---|
params | CreateUserParams | An object containing the attributes for the user to create; required and enabled fields depend on Clerk Dashboard settings. |
Returns
Promise<User>
Key points
- The method creates a new User record in the current Clerk instance.
- The Dashboard configuration controls the shape and requirements of created users.
- Every attribute configured as Required must appear in the creation request.
- Reserved contact identifiers remain unverified while still supporting sign-in and preventing ownership by another user.
- Development instances permit up to 100 creation requests in a 10-second window.
- Production instances have a higher limit of 1000 requests per 10 seconds.
Common mistakes
- Only provide attributes enabled in the Clerk Dashboard; unsupported fields cause the request to fail.
- Do not assume newly supplied contact identifiers remain unverified; the default behavior marks them verified.
- Bulk creation must account for endpoint throttling.
Example: Create a user with the Backend SDK
import { createClerkClient } from '@clerk/backend'
const clerk = createClerkClient({
secretKey: process.env.CLERK_SECRET_KEY,
})
const user = await clerk.users.createUser({
emailAddress: ['test@example.com'],
password: 'my-secure-password',
})
console.log(user.id)Creates a Clerk user with an email address and password, then prints the returned user ID.
When to use it
User migration
Import accounts from another identity system.
Reserved identifier creation
Create a sign-in identifier without claiming it as verified ownership.
Interview questions
QWhat does users.createUser return and what API does it wrap?
The method signature is function createUser(params: CreateUserParams): Promise<User>. It is the Backend SDK wrapper for the Backend API POST/users, so it returns the created User object.
Follow-up: What determines which fields are mandatory? The instance's Clerk Dashboard settings do: fields marked Required must be included when creating the user.
QHow do Clerk settings affect user creation?
The instance configuration determines the user model. Required settings must be satisfied, and attempting to send a field that is not enabled produces an error.
Follow-up: How would you diagnose a rejected field? Compare the request with the enabled and required user attributes in the Clerk Dashboard.
QHow are contact identifiers treated during creation?
Email addresses and phone numbers are automatically verified by default. To create one as reserved instead, use emailAddressIdentificationStatus or phoneNumberIdentificationStatus; reserved identifiers are unverified but usable for sign-in and cannot be claimed by another user.
Follow-up: What operational concern applies to repeated calls? Respect the endpoint limits: development allows 100 requests per 10 seconds, while production allows 1000.
Related
CreateUserParamsUseremailAddressIdentificationStatusphoneNumberIdentificationStatusclerkClient