Skip to main content

updateUserMetadata()

Updates the metadata for the given user, by merging existing values with the provided parameters.

A "deep" merge will be performed - "deep" means that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to null.

Tip

If you want to fully replace the existing metadata instead of merging, use replaceUserMetadata().

Returns the updated User.

function updateUserMetadata(userId: string, params: { privateMetadata?: UserPrivateMetadata; publicMetadata?: UserPublicMetadata; unsafeMetadata?: UserUnsafeMetadata }): Promise<User>

Parameters

  • Name
    userId
    Type
    string
    Description

    The ID of the user to update.

  • Name
    params
    Type
    { privateMetadata?: UserPrivateMetadata; publicMetadata?: UserPublicMetadata; unsafeMetadata?: UserUnsafeMetadata; }
    Description

    The metadata to update.

  • Name
    params.privateMetadata?
    Type
    UserPrivateMetadata
    Description

    Metadata that can be read and set only from the Backend API.

  • Name
    params.publicMetadata?
    Type
    UserPublicMetadata
    Description

    Metadata that can be read from the Frontend API and Backend API and can be set only from the Backend API.

  • Name
    params.unsafeMetadata?
    Type
    UserUnsafeMetadata
    Description

    Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the Frontend API.

Usage

Note

Using clerkClient varies based on the SDK you're using. Refer to the overview for usage details, including guidance on how to access the userId and other properties.

const userId = 'user_123'

const response = await clerkClient.users.updateUserMetadata(userId, {
  publicMetadata: {
    example: 'metadata',
  },
})

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint PATCH/users/{user_id}/metadata. See the BAPI reference for more information.

Here's an example of making a request directly to the endpoint using cURL.

curl.sh
curl -XPATCH -H 'Authorization: Bearer YOUR_SECRET_KEY' -H "Content-type: application/json" -d '{
  "public_metadata": {
    "birthday": "1990-01-01"
  }
}' 'https://api.clerk.com/v1/users/{user_id}/metadata'

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub