Change a user's name or username from a trusted backend.
Profile administration
Clerk · Module
users.updateUser
Updates a Clerk user by ID with selected optional attributes and returns the updated user. It is the backend SDK wrapper for Clerk's PATCH user endpoint.
How it works
Call the backend users service with a user ID and an object containing only the attributes to change. The method sends a PATCH request to Clerk's Backend API and resolves with the updated User resource; omitted optional fields remain unchanged.
Syntax
function updateUser(userId: string, params: UpdateUserParams): Promise<User>Parameters
| Name | Type | Description |
|---|---|---|
userId | string | The ID of the user to update. |
params | object | Optional user fields to update, including names, username, locale, password, contact-method IDs, metadata, and account settings. |
Returns
A promise resolving to the updated User.
Key points
updateUserchanges attributes on the user identified by the supplied ID.- The required
userIdargument identifies which Clerk user receives the update. params.firstNameoptionally replaces the user's first name.- The optional locale must follow BCP-47 formatting, such as
en-US. - Setting
notifyPrimaryEmailAddressChangedrequests notification when the primary email changes. - The documented JavaScript/TypeScript usage awaits the result from
clerkClient.users.updateUser. - At the API level, the SDK maps the method to a PATCH request for the selected user.
Common mistakes
- This is a backend operation backed by Clerk's PATCH user endpoint, so it should run in a trusted server environment.
Example: Update a user's name
import { clerkClient } from '@clerk/backend'
const updatedUser = await clerkClient.users.updateUser('user_123', {
firstName: 'John',
lastName: 'Wick',
})
console.log(updatedUser.firstName, updatedUser.lastName)Updates the specified user's first and last names and returns the updated user.
When to use it
Update locale, timezone, password, or primary contact-method identifiers.
Account settings
Sign the user out of other sessions while applying an account change.
Session control
Adjust whether the user can create organizations and their creation limit.
Organization administration
Interview questions
QWhat does users.updateUser do and what are its main arguments?
It accepts a user ID and an object of optional update parameters, then returns the updated user. The SDK implements it by wrapping Clerk's Backend API PATCH endpoint for that user.
Follow-up: How would you update only a user's first name? Pass the user ID and an object such as { firstName: 'Ada' }; unspecified fields are not part of that update request.
QShow a typical call that changes a user's name.
Use await clerkClient.users.updateUser(userId, { firstName, lastName }). The returned promise resolves to the updated user resource, which can then be used or serialized by the server.
Follow-up: How can the caller request that other sessions be invalidated? Include signOutOfOtherSessions: true in the parameter object.
QWhat kinds of user attributes can be supplied?
The method supports many optional attributes, including names, username, locale, contact-method IDs, password, session sign-out behavior, and organization-creation settings. Locale values use BCP-47 formatting such as en-US.
Follow-up: What should be used for metadata changes in newer Clerk guidance? Prefer the dedicated metadata update methods rather than passing metadata directly to this method.
Related
UserclerkClientupdateUserMetadatareplaceUserMetadataupdateOrganizationMetadata