Clerk API (unofficial showcase)
PATCH/users/{user_id}

Update a user

Update a user's attributes.

You can set the user's primary contact identifiers (email address and phone numbers) by updating the primary_email_address_id and primary_phone_number_id attributes respectively. Both IDs should correspond to verified identifications that belong to the user.

You can remove a user's username by setting the username attribute to null or the blank string "".

As of API version 2026-05-12, this endpoint no longer accepts public_metadata, private_metadata, or unsafe_metadata. Use PATCH /v1/users/{user_id}/metadata to merge updates into existing metadata, or PUT /v1/users/{user_id}/metadata to replace a metadata field entirely.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 25 body fields
user_idstringrequired
The ID of the user to update
external_idstringoptional
The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.
first_namestringoptional
The first name to assign to the user
last_namestringoptional
The last name to assign to the user
localestringoptional
The locale to assign to the user (e.g., "en-US", "fr-FR")
timezonestringoptional
The IANA timezone to assign to the user (e.g., "America/New_York", "Europe/Paris"). Set to null to clear it and allow automatic capture on a later trusted sign-in.
primary_email_address_idstringoptional
The ID of the email address to set as primary. It must be verified, and present on the current user.
notify_primary_email_address_changedbooleanoptional
If set to `true`, the user will be notified that their primary email address has changed. By default, no notification is sent.
Default:false
primary_phone_number_idstringoptional
The ID of the phone number to set as primary. It must be verified, and present on the current user.
primary_web3_wallet_idstringoptional
The ID of the web3 wallets to set as primary. It must be verified, and present on the current user.
usernamestringoptional
The username to give to the user. It must be unique across your instance.
profile_image_idstringoptional
The ID of the image to set as the user's profile image
passwordstringoptional
The plaintext password to give the user. Must be at least 8 characters long, and cannot be in any list of hacked passwords.
password_digeststringoptional
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.
password_hasherstringoptional
The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), `pbkdf2_sha512`, [`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2), [`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html), the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`, `sha512_symfony`, the SHA-512 variant of the [Symfony](https://symfony.com/doc/current/security/passwords.html) 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](https://clerk.com/docs/references/backend/user/create-user) for more information.
skip_password_checksbooleanoptional
Set it to `true` if you're updating the user's password and want to skip any password policy settings check. This parameter can only be used when providing a `password`.
sign_out_of_other_sessionsbooleanoptional
Set to `true` to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a `password`.
totp_secretstringoptional
In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it.
backup_codesarray<string>optional
If Backup Codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them.
delete_self_enabledbooleanoptional
If true, the user can delete themselves with the Frontend API.
create_organization_enabledbooleanoptional
If true, the user can create organizations with the Frontend API.
legal_accepted_atstringoptional
A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format.
skip_legal_checksbooleanoptional
When set to `true` all legal checks are skipped.
create_organizations_limitintegeroptional
The maximum number of organizations the user can create. 0 means unlimited.
created_atstringoptional
A custom date/time denoting _when_ the user signed up to the application.
bypass_client_trustbooleanoptional
When set to `true`, the user will bypass Device Trust checks during sign-in.

6 status codes
200Success
idstringrequired
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:user
external_idstringrequired
primary_email_address_idstringrequired
primary_phone_number_idstringrequired
primary_web3_wallet_idstringrequired
usernamestringrequired
first_namestringrequired
last_namestringrequired
localestringoptional
timezonestringoptional
profile_image_urlstringdeprecatedoptional
image_urlstringoptional
has_imagebooleanrequired
public_metadataobjectrequired
private_metadataobjectoptional
unsafe_metadataobjectoptional
email_addressesarray<object>required
phone_numbersarray<object>required
web3_walletsarray<object>required
passkeysarray<object>required
password_enabledbooleanrequired
two_factor_enabledbooleanrequired
totp_enabledbooleanrequired
backup_code_enabledbooleanrequired
mfa_enabled_atintegerrequired
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.
mfa_disabled_atintegerrequired
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.
password_last_updated_atintegeroptional
Unix timestamp of when the user's password was last updated.
external_accountsarray<object>required
saml_accountsarray<object>required
enterprise_accountsarray<object>required
organization_membershipsarray<object>optional
last_sign_in_atintegerrequired
Unix timestamp of last sign-in.
bannedbooleanrequired
Flag to denote whether user is banned or not.
lockedbooleanrequired
Flag to denote whether user is currently locked, i.e. restricted from signing in or not.
deprovisionedbooleanoptional
Flag to denote whether user has been deprovisioned and is restricted from signing in.
lockout_expires_in_secondsintegerrequired
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.
verification_attempts_remainingintegerrequired
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.
updated_atintegerrequired
Unix timestamp of last update.
created_atintegerrequired
Unix timestamp of creation.
delete_self_enabledbooleanrequired
If enabled, user can delete themselves via FAPI.
create_organization_enabledbooleanrequired
If enabled, user can create organizations via FAPI.
create_organizations_limitintegeroptional
The maximum number of organizations the user can create. 0 means unlimited.
last_active_atintegerrequired
Unix timestamp of the latest session activity, with day precision.
legal_accepted_atintegerrequired
Unix timestamp of when the user accepted the legal requirements.
bypass_client_trustbooleanoptional
When set to `true`, the user will bypass Device Trust checks during sign-in.
Default:false
directoriesarray<object>optional
All loaded directory links. Omitted when links were not loaded; an empty array means the user has no directory links.
directoryobjectdeprecatedoptional
The most recently updated directory link. Use directories for all links.
scimobjectdeprecatedoptional
Alias of directory. Use directories for all links.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
409Conflict
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 404 is returned: Resource not found. A 409 is returned: Conflict. A 422 is returned: Invalid request parameters.