Users

Replace a user's metadata

Changed on

Replace a user's metadata attributes with the provided values.

Unlike PATCH /v1/users/{user_id}/metadata (merge semantics), this endpoint replaces the supplied metadata fields entirely — the prior contents of each supplied field are discarded. Fields omitted from the request body are left unchanged.

Prefer the PATCH endpoint for partial updates. Use PUT only when you explicitly intend to overwrite a metadata field wholesale.

put/users/{user_id}/metadata

Request

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

Path parameters

user_idstring required

The ID of the user whose metadata will be replaced

Request body

public_metadataobject

Metadata saved on the user, that is visible to both your frontend and backend. The existing value will be replaced entirely with the new object.

private_metadataobject

Metadata saved on the user that is only visible to your backend. The existing value will be replaced entirely with the new object.

unsafe_metadataobject

Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. The existing value will be replaced entirely with the new object.

Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.

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