Users

Update a user

Changed on

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 "". This is a destructive action; the identification will be deleted forever. Usernames can be removed only if they are optional in your instance settings and there's at least one other identifier which can be used for authentication.

This endpoint allows changing a user's password. When passing the password parameter directly you have two further options. You can ignore the password policy checks for your instance by setting the skip_password_checks parameter to true. You can also choose to sign the user out of all their active sessions on any device once the password is updated. Just set sign_out_of_other_sessions to true.

patch/users/{user_id}

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/users/{user_id}
  • Auth: HTTP bearer

Path parameters

user_idstring required

The ID of the user to update

Request body

external_idstring nullable

The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.

first_namestring nullable

The first name to assign to the user

last_namestring nullable

The last name to assign to the user

localestring nullable

The locale to assign to the user (e.g., "en-US", "fr-FR")

timezonestring nullable

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_idstring nullable

The ID of the email address to set as primary. It must be verified, and present on the current user.

notify_primary_email_address_changedboolean nullable

If set to true, the user will be notified that their primary email address has changed. By default, no notification is sent.

primary_phone_number_idstring nullable

The ID of the phone number to set as primary. It must be verified, and present on the current user.

primary_web3_wallet_idstring nullable

The ID of the web3 wallets to set as primary. It must be verified, and present on the current user.

usernamestring nullable

The username to give to the user. It must be unique across your instance.

profile_image_idstring nullable

The ID of the image to set as the user's profile image

passwordstring nullable

The plaintext password to give the user. Must be at least 8 characters long, and cannot be in any list of hacked passwords.

password_digeststring

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_hasherstring

The hashing algorithm that was used to generate the password digest.

The algorithms we support at the moment are bcrypt, bcrypt_sha256_django, md5, pbkdf2_sha1, pbkdf2_sha256, pbkdf2_sha256_django, pbkdf2_sha512, phpass, md5_phpass, scrypt_firebase, scrypt_werkzeug, sha256, ldap_ssha, the argon2 variants: argon2i and argon2id, sha512_symfony, the SHA-512 variant of the Symfony 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 for more information.

skip_password_checksboolean nullable

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_sessionsboolean nullable

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_secretstring nullable

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. Please note that currently the supported options are:

  • Period: 30 seconds
  • Code length: 6 digits
  • Algorithm: SHA1
backup_codesstring[]

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. You must provide the backup codes in plain format or the corresponding bcrypt digest.

public_metadataobject nullable

Metadata saved on the user, that is visible to both your Frontend and Backend APIs. Deprecated: As of API version 2026-05-12, this field is rejected on PATCH /v1/users/{user_id}. 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.

private_metadataobject nullable

Metadata saved on the user, that is only visible to your Backend API. Deprecated: As of API version 2026-05-12, this field is rejected on PATCH /v1/users/{user_id}. 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.

unsafe_metadataobject nullable

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. Deprecated: As of API version 2026-05-12, this field is rejected on PATCH /v1/users/{user_id}. 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.

delete_self_enabledboolean nullable

If true, the user can delete themselves with the Frontend API.

create_organization_enabledboolean nullable

If true, the user can create organizations with the Frontend API.

legal_accepted_atstring nullable

A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

skip_legal_checksboolean nullable

When set to true all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk.

create_organizations_limitinteger nullable

The maximum number of organizations the user can create. 0 means unlimited.

created_atstring nullable

A custom date/time denoting when the user signed up to the application, specified in RFC3339 format (e.g. 2012-10-20T07:15:20.902Z).

bypass_client_trustboolean nullable

When set to true, the user will bypass Device Trust checks during sign-in.

Response

Success

idstring required
object'user' required

String representing the object's type. Objects of the same type share the same value.

external_idstring nullable required
primary_email_address_idstring nullable required
primary_phone_number_idstring nullable required
primary_web3_wallet_idstring nullable required
usernamestring nullable required
first_namestring nullable required
last_namestring nullable required
localestring nullable
timezonestring nullable
profile_image_urlstring
image_urlstring
has_imageboolean required
public_metadataobject required
private_metadataobject nullable
unsafe_metadataobject
password_enabledboolean required
two_factor_enabledboolean required
totp_enabledboolean required
backup_code_enabledboolean required
mfa_enabled_atinteger nullable required

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_atinteger nullable required

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_atinteger nullable

Unix timestamp of when the user's password was last updated.

last_sign_in_atinteger nullable required

Unix timestamp of last sign-in.

bannedboolean required

Flag to denote whether user is banned or not.

lockedboolean required

Flag to denote whether user is currently locked, i.e. restricted from signing in or not.

deprovisionedboolean

Flag to denote whether user has been deprovisioned and is restricted from signing in.

lockout_expires_in_secondsinteger nullable required

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_remaininginteger nullable required

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_atinteger required

Unix timestamp of last update.

created_atinteger required

Unix timestamp of creation.

delete_self_enabledboolean required

If enabled, user can delete themselves via FAPI.

create_organization_enabledboolean required

If enabled, user can create organizations via FAPI.

create_organizations_limitinteger nullable

The maximum number of organizations the user can create. 0 means unlimited.

last_active_atinteger nullable required

Unix timestamp of the latest session activity, with day precision.

legal_accepted_atinteger nullable required

Unix timestamp of when the user accepted the legal requirements.

bypass_client_trustboolean

When set to true, the user will bypass Device Trust checks during sign-in.

Example response

{
  "last_active_at": 1700690400000,
  "legal_accepted_at": 1700690400000
}

Changes

  • 2025-11-10a490313abffaRevision changes
    • warning

      removed the optional property /////// from the response with the status

  • 2025-11-107db12d6a9b2aRevision changes
    • info

      added the optional property /////// to the response with the status