---
title: "Update a user"
method: PATCH
path: "/users/{user_id}"
tags: ["Users"]
---

# Update a user

`PATCH /users/{user_id}`

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.

## Path parameters

- `user_id` string, required

## Request body

- object
  - `external_id` string, nullable — The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.
  - `first_name` string, nullable — The first name to assign to the user
  - `last_name` string, nullable — The last name to assign to the user
  - `locale` string, nullable — The locale to assign to the user (e.g., "en-US", "fr-FR")
  - `primary_email_address_id` string, 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_changed` boolean, 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_id` string, nullable — The ID of the phone number to set as primary. It must be verified, and present on the current user.
  - `primary_web3_wallet_id` string, nullable — The ID of the web3 wallets to set as primary. It must be verified, and present on the current user.
  - `username` string, nullable — The username to give to the user. It must be unique across your instance.
  - `profile_image_id` string, nullable — The ID of the image to set as the user's profile image
  - `password` string, 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_digest` string — 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_hasher` string — 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_checks` boolean, 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_sessions` boolean, 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_secret` string, 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.
  - `backup_codes` string[] — 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_enabled` boolean, nullable — If true, the user can delete themselves with the Frontend API.
  - `create_organization_enabled` boolean, nullable — If true, the user can create organizations with the Frontend API.
  - `legal_accepted_at` string, nullable — A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format.
  - `skip_legal_checks` boolean, nullable — When set to `true` all legal checks are skipped.
  - `create_organizations_limit` integer, nullable — The maximum number of organizations the user can create. 0 means unlimited.
  - `created_at` string, nullable — A custom date/time denoting _when_ the user signed up to the application.
  - `bypass_client_trust` boolean, nullable — When set to `true`, the user will bypass client trust checks during sign-in.

## Response `200`

Success

- User
  - `id` string, required
  - `object` 'user', required — String representing the object's type. Objects of the same type share the same value.
  - `external_id` string, nullable, required
  - `primary_email_address_id` string, nullable, required
  - `primary_phone_number_id` string, nullable, required
  - `primary_web3_wallet_id` string, nullable, required
  - `username` string, nullable, required
  - `first_name` string, nullable, required
  - `last_name` string, nullable, required
  - `locale` string, nullable
  - `profile_image_url` string
  - `image_url` string
  - `has_image` boolean, required
  - `public_metadata` object, required
  - `private_metadata` object, nullable
  - `unsafe_metadata` object
  - `email_addresses` EmailAddress[], required
    - `id` string
    - `object` 'email_address', required — String representing the object's type. Objects of the same type share the same value.
    - `email_address` string, required
    - `reserved` boolean, required
    - `verification` union, required
      - object
        - `object` 'verification_otp'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
        - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `channel` string, nullable — The delivery channel of the code (phone codes only).
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_admin'
        - `status` 'verified', required
        - `strategy` 'admin', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_from_oauth'
        - `status` 'unverified' | 'verified', required
        - `strategy` string, required
        - `error` object, nullable
          - `message` string, required
          - `long_message` string, required
          - `code` string, required
          - `meta` object
        - `expire_at` integer, nullable, required
        - `attempts` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_ticket'
        - `status` 'unverified' | 'verified' | 'expired', required
        - `strategy` 'ticket', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_saml'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
        - `strategy` 'saml', required
        - `external_verification_redirect_url` string, nullable
        - `error` object, nullable
          - `message` string, required
          - `long_message` string, required
          - `code` string, required
          - `meta` object
        - `expire_at` integer, nullable
        - `attempts` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_email_link'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
        - `strategy` 'email_link', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_scim'
        - `status` 'verified', required
        - `strategy` 'scim', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
    - `linked_to` IdentificationLink[], required
      - `type` string, required
      - `id` string, required
    - `matches_sso_connection` boolean — Indicates whether this email address domain matches an active enterprise connection.
    - `created_at` integer, required — Unix timestamp of creation
    - `updated_at` integer, required — Unix timestamp of creation
  - `phone_numbers` PhoneNumber[], required
    - `id` string
    - `object` 'phone_number', required — String representing the object's type. Objects of the same type share the same value.
    - `phone_number` string, required
    - `reserved_for_second_factor` boolean
    - `default_second_factor` boolean
    - `reserved` boolean, required
    - `verification` union, required
      - object
        - `object` 'verification_otp'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
        - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `channel` string, nullable — The delivery channel of the code (phone codes only).
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_admin'
        - `status` 'verified', required
        - `strategy` 'admin', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
    - `linked_to` IdentificationLink[], required
      - `type` string, required
      - `id` string, required
    - `backup_codes` string[], nullable
    - `created_at` integer, required — Unix timestamp of creation
    - `updated_at` integer, required — Unix timestamp of creation
  - `web3_wallets` Web3Wallet[], required
    - `id` string
    - `object` 'web3_wallet', required — String representing the object's type. Objects of the same type share the same value.
    - `web3_wallet` string, required
    - `verification` union, required
      - object
        - `object` 'verification_web3'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
        - `strategy` 'web3_metamask_signature' | 'web3_base_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'web3_solana_signature', required
        - `nonce` string, nullable
        - `message` string, nullable
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_admin'
        - `status` 'verified', required
        - `strategy` 'admin', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
    - `created_at` integer, required — Unix timestamp of creation
    - `updated_at` integer, required — Unix timestamp of creation
  - `passkeys` Passkey[], required
    - `id` string
    - `object` 'passkey', required — String representing the object's type. Objects of the same type share the same value.
    - `name` string, required
    - `last_used_at` integer, required — Unix timestamp of when the passkey was last used.
    - `verification` object, nullable, required
      - `object` 'verification_passkey'
      - `status` 'verified', required
      - `strategy` 'passkey', required
      - `nonce` 'nonce'
      - `message` string, nullable
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
      - `verified_at_client` string, nullable
  - `password_enabled` boolean, required
  - `two_factor_enabled` boolean, required
  - `totp_enabled` boolean, required
  - `backup_code_enabled` boolean, required
  - `mfa_enabled_at` integer, 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_at` integer, 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_at` integer, nullable — Unix timestamp of when the user's password was last updated.
  - `external_accounts` ExternalAccountWithVerification[], required
    - `object` 'external_account' | 'facebook_account' | 'google_account', required — String representing the object's type. Objects of the same type share the same value.
    - `id` string, required
    - `provider` string, required
    - `identification_id` string, required
    - `provider_user_id` string, required — The unique ID of the user in the external provider's system
    - `approved_scopes` string, required
    - `email_address` string, required
    - `email_address_verified` boolean, nullable — Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified
    - `first_name` string, required
    - `last_name` string, required
    - `avatar_url` string — Please use `image_url` instead
    - `image_url` string, nullable
    - `username` string, nullable
    - `phone_number` string, nullable
    - `public_metadata` object, required
    - `label` string, nullable
    - `created_at` integer, required — Unix timestamp of creation
    - `updated_at` integer, required — Unix timestamp of creation
    - `verification` union, required
      - object
        - `object` 'verification_oauth'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
        - `strategy` string, required
        - `external_verification_redirect_url` string
        - `error` object, nullable
          - `message` string, required
          - `long_message` string, required
          - `code` string, required
          - `meta` object
        - `expire_at` integer, required
        - `attempts` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_google_one_tap'
        - `status` 'unverified' | 'verified', required
        - `strategy` 'google_one_tap', required
        - `expire_at` integer, nullable, required
        - `attempts` integer, nullable, required
        - `verified_at_client` string, nullable
        - `error` object, nullable
          - `message` string, required
          - `long_message` string, required
          - `code` string, required
          - `meta` object
  - `saml_accounts` SAMLAccount[], required
    - `id` string, required
    - `object` 'saml_account', required — String representing the object's type. Objects of the same type share the same value.
    - `provider` string, required
    - `active` boolean, required
    - `email_address` string, required
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `provider_user_id` string, nullable
    - `last_authenticated_at` integer, nullable — Unix timestamp of last authentication.
    - `public_metadata` object
    - `verification` union, required
      - object
        - `object` 'verification_saml'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
        - `strategy` 'saml', required
        - `external_verification_redirect_url` string, nullable
        - `error` object, nullable
          - `message` string, required
          - `long_message` string, required
          - `code` string, required
          - `meta` object
        - `expire_at` integer, nullable
        - `attempts` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_ticket'
        - `status` 'unverified' | 'verified' | 'expired', required
        - `strategy` 'ticket', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
    - `saml_connection` union
      - object
        - `id` string, required
        - `name` string, required
        - `domain` string, required
        - `domains` string[]
        - `active` boolean, required
        - `provider` string, required
        - `sync_user_attributes` boolean, required
        - `allow_subdomains` boolean
        - `allow_idp_initiated` boolean
        - `disable_additional_identifications` boolean
        - `created_at` integer, required — Unix timestamp of creation.
        - `updated_at` integer, required — Unix timestamp of last update.
      - object
        - `id` string, required
        - `name` string, required
        - `domain` string
        - `domains` string[], required
        - `active` boolean, required
        - `provider` string, required
        - `sync_user_attributes` boolean, required
        - `allow_subdomains` boolean
        - `allow_idp_initiated` boolean
        - `disable_additional_identifications` boolean
        - `created_at` integer, required — Unix timestamp of creation.
        - `updated_at` integer, required — Unix timestamp of last update.
  - `enterprise_accounts` EnterpriseAccount[], required
    - `id` string, required
    - `object` 'enterprise_account', required — String representing the object's type. Objects of the same type share the same value.
    - `protocol` 'oauth' | 'saml' — The authentication protocol used to sign in.
    - `provider` string, required
    - `active` boolean, required
    - `email_address` string, required
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `provider_user_id` string, nullable — The unique ID of the user in the external provider's system
    - `enterprise_connection_id` string, nullable
    - `public_metadata` object
    - `verification` union, required
      - object
        - `object` 'verification_ticket'
        - `status` 'unverified' | 'verified' | 'expired', required
        - `strategy` 'ticket', required
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_saml'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
        - `strategy` 'saml', required
        - `external_verification_redirect_url` string, nullable
        - `error` object, nullable
          - `message` string, required
          - `long_message` string, required
          - `code` string, required
          - `meta` object
        - `expire_at` integer, nullable
        - `attempts` integer, nullable, required
        - `verified_at_client` string, nullable
      - object
        - `object` 'verification_oauth'
        - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
        - `strategy` string, required
        - `external_verification_redirect_url` string
        - `error` object, nullable
          - `message` string, required
          - `long_message` string, required
          - `code` string, required
          - `meta` object
        - `expire_at` integer, required
        - `attempts` integer, nullable, required
        - `verified_at_client` string, nullable
    - `enterprise_connection` union
      - object
        - `id` string, required
        - `protocol` string, required
        - `provider` string, required
        - `name` string, required
        - `logo_public_url` string, nullable, required
        - `domain` string, required
        - `domains` string[]
        - `active` boolean, required
        - `sync_user_attributes` boolean, required
        - `allow_subdomains` boolean, required
        - `allow_idp_initiated` boolean, required
        - `disable_additional_identifications` boolean, required
        - `created_at` integer, required — Unix timestamp of creation.
        - `updated_at` integer, required — Unix timestamp of last update.
      - object
        - `id` string, required
        - `protocol` string, required
        - `provider` string, required
        - `name` string, required
        - `logo_public_url` string, nullable, required
        - `domain` string
        - `domains` string[], required
        - `active` boolean, required
        - `sync_user_attributes` boolean, required
        - `allow_subdomains` boolean, required
        - `allow_idp_initiated` boolean, required
        - `disable_additional_identifications` boolean, required
        - `created_at` integer, required — Unix timestamp of creation.
        - `updated_at` integer, required — Unix timestamp of last update.
    - `last_authenticated_at` integer, nullable — Unix timestamp of last authentication.
  - `organization_memberships` OrganizationMembership[]
    - `id` string, required
    - `object` 'organization_membership', required — String representing the object's type. Objects of the same type share the same value.
    - `role` string, required
    - `role_name` string
    - `permissions` string[], required
    - `public_metadata` object, required — Metadata saved on the organization membership, accessible from both Frontend and Backend APIs
    - `private_metadata` object — Metadata saved on the organization membership, accessible only from the Backend API
    - `organization` Organization, required
      - `object` 'organization', required
      - `id` string, required
      - `name` string, required
      - `slug` string, required
      - `image_url` string
      - `has_image` boolean, required
      - `members_count` integer
      - `missing_member_with_elevated_permissions` boolean
      - `pending_invitations_count` integer
      - `max_allowed_memberships` integer, required
      - `admin_delete_enabled` boolean, required
      - `public_metadata` object, required
      - `private_metadata` object
      - `created_by` string
      - `created_at` integer, required — Unix timestamp of creation.
      - `updated_at` integer, required — Unix timestamp of last update.
      - `last_active_at` integer — Unix timestamp of last activity.
      - `role_set_key` string, nullable — The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
    - `public_user_data` OrganizationMembershipPublicUserData — An organization membership with public user data populated
      - `user_id` string, required
      - `first_name` string, nullable, required
      - `last_name` string, nullable, required
      - `profile_image_url` string, nullable, required
      - `image_url` string, required
      - `has_image` boolean, required
      - `identifier` string, nullable
      - `username` string, nullable
      - `banned` boolean
      - `deprovisioned` boolean
    - `created_at` integer, required — Unix timestamp of creation.
    - `updated_at` integer, required — Unix timestamp of last update.
  - `last_sign_in_at` integer, nullable, required — Unix timestamp of last sign-in.
  - `banned` boolean, required — Flag to denote whether user is banned or not.
  - `locked` boolean, required — Flag to denote whether user is currently locked, i.e. restricted from signing in or not.
  - `deprovisioned` boolean — Flag to denote whether user has been deprovisioned and is restricted from signing in.
  - `lockout_expires_in_seconds` integer, 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_remaining` integer, 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_at` integer, required — Unix timestamp of last update.
  - `created_at` integer, required — Unix timestamp of creation.
  - `delete_self_enabled` boolean, required — If enabled, user can delete themselves via FAPI.
  - `create_organization_enabled` boolean, required — If enabled, user can create organizations via FAPI.
  - `create_organizations_limit` integer, nullable — The maximum number of organizations the user can create. 0 means unlimited.
  - `last_active_at` integer, nullable, required — Unix timestamp of the latest session activity, with day precision.
  - `legal_accepted_at` integer, nullable, required — Unix timestamp of when the user accepted the legal requirements.
  - `bypass_client_trust` boolean — When set to `true`, the user will bypass client trust checks during sign-in.
  - `scim` SCIMUserMetadata — Metadata describing a user's linkage to a SCIM directory. This object is only delivered on `user.created` and `user.updated` webhook events, and only when the user is provisioned through a SCIM directory. Its absence does not necessarily mean the user is not SCIM-managed.
    - `directory_id` string, required — The ID of the SCIM directory the user is provisioned from.
    - `directory_enabled` boolean — Whether the SCIM directory is currently enabled. Omitted when false.
    - `external_id` string, nullable, required — The user's external ID as reported by the SCIM directory, if any.

## Other responses

- `400` — Request was not successful
- `401` — Authentication invalid
- `404` — Resource not found
- `409` — Conflict
- `422` — Invalid request parameters

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/versions/cf036e7951d3/schema)