From 70920c3022308deb3eba65bcd53ab770a83598b7 Mon Sep 17 00:00:00 2001 From: brunol95 Date: Mon, 18 May 2026 16:35:30 -0400 Subject: [PATCH 1/4] draft for new api versionn changes --- docs/_partials/user-object.mdx | 2 +- .../development/add-onboarding-flow.mdx | 2 +- .../upgrading/upgrade-guides/2026-05-12.mdx | 66 +++++++++++++++ .../upgrading/upgrade-guides/core-3.mdx | 36 ++++++++ .../development/upgrading/versioning.mdx | 29 +++++++ docs/manifest.json | 8 ++ .../backend/user/replace-user-metadata.mdx | 84 +++++++++++++++++++ .../backend/user/update-user-metadata.mdx | 10 +++ docs/reference/backend/user/update-user.mdx | 12 +-- docs/reference/objects/user.mdx | 4 +- 10 files changed, 243 insertions(+), 10 deletions(-) create mode 100644 docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx create mode 100644 docs/reference/backend/user/replace-user-metadata.mdx diff --git a/docs/_partials/user-object.mdx b/docs/_partials/user-object.mdx index 334fba0463..495a986a9a 100644 --- a/docs/_partials/user-object.mdx +++ b/docs/_partials/user-object.mdx @@ -2,4 +2,4 @@ The `User` object holds all of the information for a single user of your applica A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address or phone number, but only one of them will be their primary email address (`User.primaryEmailAddress`) or primary phone number (`User.primaryPhoneNumber`). At the same time, a user can also have one or more external accounts by connecting to [social providers](/docs/guides/configure/auth-strategies/social-connections/overview) such as Google, Apple, Facebook, and many more (`User.externalAccounts`). -Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/guides/users/extending) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](/docs/reference/frontend-api){{ target: '_blank' }}. +Finally, a `User` object holds profile data like the user's name, profile picture, and a set of [metadata](/docs/guides/users/extending) that can be used internally to store arbitrary information. The metadata are split into `publicMetadata` and `privateMetadata`. Both types are set from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }} via [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata), but public metadata can also be accessed from the [Frontend API](/docs/reference/frontend-api){{ target: '_blank' }}. diff --git a/docs/guides/development/add-onboarding-flow.mdx b/docs/guides/development/add-onboarding-flow.mdx index 479e3413bd..858e18dccc 100644 --- a/docs/guides/development/add-onboarding-flow.mdx +++ b/docs/guides/development/add-onboarding-flow.mdx @@ -230,7 +230,7 @@ export const completeOnboarding = async (formData: FormData) => { const client = await clerkClient() try { - const res = await client.users.updateUser(userId, { + const res = await client.users.updateUserMetadata(userId, { publicMetadata: { onboardingComplete: true, applicationName: formData.get('applicationName'), diff --git a/docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx b/docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx new file mode 100644 index 0000000000..7189dd6e72 --- /dev/null +++ b/docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx @@ -0,0 +1,66 @@ +--- +title: Upgrade to API version 2026-05-12 +description: Learn how to upgrade to version 2026-05-12 of Clerk's API. +--- + +**Version 2026-05-12** of Clerk's Frontend and Backend APIs removes user metadata fields from the general-purpose user update endpoints. Metadata must now be set through the dedicated metadata endpoints, which provide deep-merge semantics. + +To use this new API version, refer to the [versioning guide](/docs/guides/development/upgrading/versioning). This guide documents all updates at the API level. Since implementation details may differ between SDKs, it will help you identify which parts of your SDK usage may require additional review in the documentation, and assist consumers using unofficial or custom API clients in managing the upgrade. + +## Backend endpoint changes + +`PATCH /v1/users/{user_id}` no longer accepts the following fields in the request body: + +- `public_metadata` +- `private_metadata` +- `unsafe_metadata` + +To update user metadata, use one of the dedicated endpoints below: + +| Endpoint | Semantics | +| - | - | +| `PATCH /v1/users/{user_id}/metadata` | Deep-merges the provided values into the existing metadata. Any key set to `null` is removed. | +| `PUT /v1/users/{user_id}/metadata` | Replaces each provided top-level metadata field in full — no merging at any level. Top-level fields omitted from the request body are left untouched. Send `{}` to clear a field, or `null` to store a JSON `null` value. | + +Choose `PATCH` when you want to update specific keys without affecting others, and `PUT` when you want to overwrite an entire metadata field. + +If you are using a Clerk SDK, use the [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata) method (which wraps `PATCH`) or the [`replaceUserMetadata()`](/docs/reference/backend/user/replace-user-metadata) method (which wraps `PUT`) instead of passing metadata fields to `updateUser()`. + +```ts {{ del: [[1, 5]], ins: [[6, 15]] }} +await clerkClient.users.updateUser(userId, { + publicMetadata: { + role: 'admin', + }, +}) +await clerkClient.users.updateUserMetadata(userId, { + publicMetadata: { + role: 'admin', + }, +}) + +await clerkClient.users.replaceUserMetadata(userId, { + publicMetadata: { + role: 'admin', + }, +}) +``` + +## Frontend endpoint changes + +`PATCH /v1/me` no longer accepts the `unsafe_metadata` field in the request body. + +To update unsafe metadata from the frontend, use the dedicated endpoint `PATCH /v1/me/metadata` instead. This endpoint deep-merges the provided value with the existing `unsafeMetadata`, and any key set to `null` is removed. + +If you are using a Clerk SDK, use the [`updateMetadata()`](/docs/reference/objects/user#update-metadata) method on the `User` object instead of passing `unsafeMetadata` to `update()`. + +```ts {{ del: [[1, 5]], ins: [[6, 8]] }} +await user.update({ + unsafeMetadata: { + ...user.unsafeMetadata, + theme: 'dark', + }, +}) +await user.updateMetadata({ + unsafeMetadata: { theme: 'dark' }, +}) +``` diff --git a/docs/guides/development/upgrading/upgrade-guides/core-3.mdx b/docs/guides/development/upgrading/upgrade-guides/core-3.mdx index dda17de22d..23c9117a0c 100644 --- a/docs/guides/development/upgrading/upgrade-guides/core-3.mdx +++ b/docs/guides/development/upgrading/upgrade-guides/core-3.mdx @@ -545,6 +545,7 @@ The following deprecated APIs have been removed from all Clerk SDKs. @clerk/types deprecated in favor of @clerk/shared/types", + "Metadata params on user.update() and updateUser() deprecated", ]} > @@ -559,6 +560,41 @@ The following deprecated APIs have been removed from all Clerk SDKs. The `@clerk/types` package will continue to re-export types from `@clerk/shared/types` for backward compatibility, but new types will only be added to `@clerk/shared/types`. + + + The `unsafeMetadata` parameter on the frontend `user.update()` method and the `publicMetadata`, `privateMetadata`, and `unsafeMetadata` parameters on the backend `clerkClient.users.updateUser()` method are deprecated. The SDKs continue to accept them for backwards compatibility and route to the dedicated metadata endpoints internally, but they will be removed in a future major version. + + Use the dedicated metadata methods instead. On the frontend, [`user.updateMetadata()`](/docs/reference/objects/user#update-metadata) and the backend [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata) method deep-merge with the existing metadata, and any key set to `null` is removed. If you need to fully replace the metadata on the backend, use [`replaceUserMetadata()`](/docs/reference/backend/user/replace-user-metadata). + + ### Frontend {{ toc: false }} + + ```ts {{ del: [[1, 5]], ins: [[6, 8]] }} + await user.update({ + unsafeMetadata: { + ...user.unsafeMetadata, + theme: 'dark', + }, + }) + await user.updateMetadata({ + unsafeMetadata: { theme: 'dark' }, + }) + ``` + + ### Backend {{ toc: false }} + + ```ts {{ del: [[1, 5]], ins: [[6, 10]] }} + await clerkClient.users.updateUser(userId, { + publicMetadata: { + role: 'admin', + }, + }) + await clerkClient.users.updateUserMetadata(userId, { + publicMetadata: { + role: 'admin', + }, + }) + ``` + ## Version requirements diff --git a/docs/guides/development/upgrading/versioning.mdx b/docs/guides/development/upgrading/versioning.mdx index 96c5aeb146..de1591e696 100644 --- a/docs/guides/development/upgrading/versioning.mdx +++ b/docs/guides/development/upgrading/versioning.mdx @@ -48,6 +48,35 @@ When making direct API calls to an endpoint, there are two options to specify th ## API versions +### 2026-05-12 + +Removes user metadata fields (`public_metadata`, `private_metadata`, `unsafe_metadata`) from `PATCH /v1/users/{user_id}` and `unsafe_metadata` from `PATCH /v1/me`. Metadata must now be set through the dedicated metadata endpoints. See the [migration guide](/docs/guides/development/upgrading/upgrade-guides/2026-05-12) for more details. + +The following SDKs are compatible with this version: + +| SDK | Version | +| - | - | +| Next.js | TBD | +| React | TBD | +| JavaScript | TBD | +| Expo | TBD | +| TanStack React Start | TBD | +| React Router | TBD | +| Express | TBD | +| Astro | TBD | +| C# | TBD | +| Chrome Extension | TBD | +| Fastify | TBD | +| Go | TBD | +| Java | TBD | +| JavaScript Backend | TBD | +| Nuxt.js | TBD | +| PHP | TBD | +| Python | TBD | +| Remix | TBD | +| Ruby | TBD | +| Vue | TBD | + ### 2025-11-10 Brings more consistency and clarity to the Clerk Billing API endpoints. See the [migration guide](/docs/guides/development/upgrading/upgrade-guides/2025-11-10) for more details. diff --git a/docs/manifest.json b/docs/manifest.json index a190172709..199c32c68b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1731,6 +1731,10 @@ { "title": "API Version 2025-11-10", "href": "/docs/guides/development/upgrading/upgrade-guides/2025-11-10" + }, + { + "title": "API Version 2026-05-12", + "href": "/docs/guides/development/upgrading/upgrade-guides/2026-05-12" } ] ] @@ -2819,6 +2823,10 @@ "title": "`updateUserMetadata()`", "href": "/docs/reference/backend/user/update-user-metadata" }, + { + "title": "`replaceUserMetadata()`", + "href": "/docs/reference/backend/user/replace-user-metadata" + }, { "title": "`deleteUser()`", "href": "/docs/reference/backend/user/delete-user" diff --git a/docs/reference/backend/user/replace-user-metadata.mdx b/docs/reference/backend/user/replace-user-metadata.mdx new file mode 100644 index 0000000000..ed320d2515 --- /dev/null +++ b/docs/reference/backend/user/replace-user-metadata.mdx @@ -0,0 +1,84 @@ +--- +title: '`replaceUserMetadata()`' +description: Use the replaceUserMetadata() method to fully replace the metadata associated with the specified user. +--- + +Replaces the metadata associated with the specified user. Unlike [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata), which deep-merges into the existing metadata, this method uses replace semantics: when a metadata field is provided, its previous value is overwritten in full with no merging at any level. + +The distinction is at two layers: + +- **Top-level field omission preserves the existing value.** Each top-level field (`publicMetadata`, `privateMetadata`, `unsafeMetadata`) is handled independently. If you don't include a field in the request, the stored value for that field is left untouched. +- **The value inside a provided field is replaced in full.** When you do include a field, its previous content is discarded — any nested keys present before but absent in the new value are dropped. There is no merge. + +For the provided field, you can also send: + +- `{}` (empty object) to clear the field. +- `null` to overwrite the field with a JSON `null` value. Prefer `{}` unless you specifically need a stored `null`. + +Returns a [`User`](/docs/reference/backend/types/backend-user) object. + +```ts +function replaceUserMetadata(userId: string, params: UserMetadataParams): Promise +``` + +## `UserMetadataParams` + + + - `userId` + - `string` + + The ID of the user to update. + + --- + + - `publicMetadata?` + - [`UserPublicMetadata`](/docs/reference/types/metadata#user-public-metadata) + + Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. When provided, the entire stored `publicMetadata` is overwritten with this value. When omitted, the existing `publicMetadata` is preserved. + + --- + + - `privateMetadata?` + - [`UserPrivateMetadata`](/docs/reference/types/metadata#user-private-metadata) + + Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. When provided, the entire stored `privateMetadata` is overwritten with this value. When omitted, the existing `privateMetadata` is preserved. + + --- + + - `unsafeMetadata?` + - [`UserUnsafeMetadata`](/docs/reference/types/metadata#user-unsafe-metadata) + + Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. When provided, the entire stored `unsafeMetadata` is overwritten with this value. When omitted, the existing `unsafeMetadata` is preserved. + + +## Usage + + + +```tsx +const userId = 'user_123' + +const response = await clerkClient.users.replaceUserMetadata(userId, { + publicMetadata: { + role: 'admin', + }, +}) +``` + +## Backend API (BAPI) endpoint + +This method in the SDK is a wrapper around the BAPI endpoint `PUT/users/{user_id}/metadata`. See the [BAPI reference](/docs/reference/backend-api/tag/users/put/users/\{user_id}/metadata){{ target: '_blank' }} for more information. + +Here's an example of making a request directly to the endpoint using cURL. + + + Replace `YOUR_SECRET_KEY` with your Clerk Secret Key. You can find your Secret Key on the [**API keys**](https://dashboard.clerk.com/~/api-keys) page in the Clerk Dashboard. + + +```bash {{ filename: 'curl.sh' }} +curl -XPUT -H 'Authorization: Bearer {{secret}}' -H "Content-type: application/json" -d '{ + "public_metadata": { + "role": "admin" + } +}' 'https://api.clerk.com/v1/users/{user_id}/metadata' +``` diff --git a/docs/reference/backend/user/update-user-metadata.mdx b/docs/reference/backend/user/update-user-metadata.mdx index ec3f6e95b9..ca05180239 100644 --- a/docs/reference/backend/user/update-user-metadata.mdx +++ b/docs/reference/backend/user/update-user-metadata.mdx @@ -9,6 +9,9 @@ Updates the metadata associated with the specified user by merging existing valu 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()`](/docs/reference/backend/user/replace-user-metadata). + Returns a [`User`](/docs/reference/backend/types/backend-user) object. ```ts @@ -36,6 +39,13 @@ function updateUserMetadata(userId: string, params: UpdateUserMetadataParams): P - [`UserPrivateMetadata`](/docs/reference/types/metadata#user-private-metadata) Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. + + --- + + - `unsafeMetadata?` + - [`UserUnsafeMetadata`](/docs/reference/types/metadata#user-unsafe-metadata) + + Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. ## Usage diff --git a/docs/reference/backend/user/update-user.mdx b/docs/reference/backend/user/update-user.mdx index d59118f5f5..89fcc1b050 100644 --- a/docs/reference/backend/user/update-user.mdx +++ b/docs/reference/backend/user/update-user.mdx @@ -140,24 +140,24 @@ function updateUser(userId: string, params: UpdateUserParams): Promise --- - - `publicMetadata?` + - `publicMetadata?` (deprecated) - [`UserPublicMetadata`](/docs/reference/types/metadata#user-public-metadata) - Metadata that can be read from the Frontend API and [Backend API](/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API. Updating this property will override the existing metadata. To merge metadata, use [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata). + Deprecated: use [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata) instead, which deep-merges rather than replacing. This parameter will be removed in a future major API version. --- - - `privateMetadata?` + - `privateMetadata?` (deprecated) - [`UserPrivateMetadata`](/docs/reference/types/metadata#user-private-metadata) - Metadata that can be read and set only from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. Updating this property will override the existing metadata. To merge metadata, use [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata). + Deprecated: use [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata) instead, which deep-merges rather than replacing. This parameter will be removed in a future major API version. --- - - `unsafeMetadata?` + - `unsafeMetadata?` (deprecated) - [`UserUnsafeMetadata`](/docs/reference/types/metadata#user-unsafe-metadata) - Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. + Deprecated: use [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata) instead, which deep-merges rather than replacing. This parameter will be removed in a future major API version. --- diff --git a/docs/reference/objects/user.mdx b/docs/reference/objects/user.mdx index 8465bdff50..7c53ebcd0f 100644 --- a/docs/reference/objects/user.mdx +++ b/docs/reference/objects/user.mdx @@ -772,10 +772,10 @@ function update(params: UpdateUserParams): Promise --- - - `unsafeMetadata?` + - `unsafeMetadata?` (deprecated) - [`UserUnsafeMetadata`](/docs/reference/types/metadata#user-unsafe-metadata) - Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the `User` object. Using `update()` to update this value fully replaces the existing value. To perform a merge, use [`updateMetadata()`](#update-metadata) instead. + Deprecated: use [`updateMetadata()`](#update-metadata) instead, which deep-merges with the existing value rather than replacing it. This parameter will be removed in a future major version. ### `updateMetadata()` From 1563598a42c7a79eb68d25b0518f990e7afd5672 Mon Sep 17 00:00:00 2001 From: brunol95 Date: Tue, 19 May 2026 14:41:30 -0400 Subject: [PATCH 2/4] update rate limit for user data --- docs/guides/how-clerk-works/system-limits.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/how-clerk-works/system-limits.mdx b/docs/guides/how-clerk-works/system-limits.mdx index 2a326cabef..1fd5b49a2c 100644 --- a/docs/guides/how-clerk-works/system-limits.mdx +++ b/docs/guides/how-clerk-works/system-limits.mdx @@ -97,7 +97,7 @@ These limits differ based on whether you're using a development or production in --- - Update a user's data or metadata - - `PATCH /v1/users/{user_id}` and `PATCH /v1/users/{user_id}/metadata` + - `PATCH /v1/users/{user_id}`, `PATCH /v1/users/{user_id}/metadata`, and `PUT /v1/users/{user_id}/metadata` 10 requests per 10 seconds per user From 5b8d164c90a972461dc94cd5435aa3966bfe0903 Mon Sep 17 00:00:00 2001 From: brunol95 Date: Wed, 20 May 2026 12:44:46 -0400 Subject: [PATCH 3/4] update mobile refs with updateMetadata method --- docs/reference/native-mobile/user.ios.mdx | 16 ++++++++++++++++ docs/reference/native-mobile/user.mdx | 22 ++++++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/docs/reference/native-mobile/user.ios.mdx b/docs/reference/native-mobile/user.ios.mdx index 408f960d2a..1189a2c6b4 100644 --- a/docs/reference/native-mobile/user.ios.mdx +++ b/docs/reference/native-mobile/user.ios.mdx @@ -22,6 +22,22 @@ let updatedUser = try await user.update(.init( )) ``` +### Update user metadata + +Use `updateMetadata` to update the user's `unsafeMetadata`. The submitted value is deep-merged into the existing metadata; use `JSON.null` for any key whose value should be removed at any nesting level. + +```swift +let updatedUser = try await user.updateMetadata(unsafeMetadata: ["theme": "dark"]) +``` + +A params overload is also available: + +```swift +let updatedUser = try await user.updateMetadata(.init(unsafeMetadata: ["theme": "dark"])) +``` + +> Note: passing `unsafeMetadata` to `user.update(...)` is deprecated. Use `user.updateMetadata(...)` for partial updates going forward. + ### Create email address ```swift diff --git a/docs/reference/native-mobile/user.mdx b/docs/reference/native-mobile/user.mdx index 40ad5dfe38..c9da538199 100644 --- a/docs/reference/native-mobile/user.mdx +++ b/docs/reference/native-mobile/user.mdx @@ -22,6 +22,28 @@ val updatedUser = user.update { } ``` +### Update user metadata + +Use `updateMetadata` to update the user's `unsafeMetadata`. The submitted value is deep-merged into the existing metadata; pass `JsonNull` for any key whose value should be removed at any nesting level. + +```kotlin +val updatedUser = user.updateMetadata( + unsafeMetadata = buildJsonObject { + put("theme", "dark") + } +) +``` + +A `UpdateMetadataParams` overload is also available when you already have the metadata as a JSON string: + +```kotlin +val updatedUser = user.updateMetadata( + User.UpdateMetadataParams(unsafeMetadata = """{"theme":"dark"}""") +) +``` + +> Note: passing `unsafeMetadata` to `user.update(...)` is deprecated. Use `user.updateMetadata(...)` for partial updates going forward. + ### Create email address ```kotlin From 3414da8f124ec6343b195f923eeb2cb5523f1adf Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Fri, 22 May 2026 12:28:04 -0500 Subject: [PATCH 4/4] docs: Fix metadata example diff highlighting, NOTE callouts, and param type name - Correct del/ins line ranges in the 2026-05-12 and Core 3 metadata examples so closing braces highlight correctly - Use > [!NOTE] callouts on the native mobile user pages - Align updateUserMetadata() param type with @clerk/backend (UserMetadataParams) Co-Authored-By: Claude Opus 4.7 (1M context) --- .../development/upgrading/upgrade-guides/2026-05-12.mdx | 4 ++-- docs/guides/development/upgrading/upgrade-guides/core-3.mdx | 2 +- docs/reference/backend/user/update-user-metadata.mdx | 4 ++-- docs/reference/native-mobile/user.ios.mdx | 3 ++- docs/reference/native-mobile/user.mdx | 3 ++- 5 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx b/docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx index 7189dd6e72..e1ca5ca646 100644 --- a/docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx +++ b/docs/guides/development/upgrading/upgrade-guides/2026-05-12.mdx @@ -26,7 +26,7 @@ Choose `PATCH` when you want to update specific keys without affecting others, a If you are using a Clerk SDK, use the [`updateUserMetadata()`](/docs/reference/backend/user/update-user-metadata) method (which wraps `PATCH`) or the [`replaceUserMetadata()`](/docs/reference/backend/user/replace-user-metadata) method (which wraps `PUT`) instead of passing metadata fields to `updateUser()`. -```ts {{ del: [[1, 5]], ins: [[6, 15]] }} +```ts {{ del: [[1, 5]], ins: [[6, 10], [12, 16]] }} await clerkClient.users.updateUser(userId, { publicMetadata: { role: 'admin', @@ -53,7 +53,7 @@ To update unsafe metadata from the frontend, use the dedicated endpoint `PATCH / If you are using a Clerk SDK, use the [`updateMetadata()`](/docs/reference/objects/user#update-metadata) method on the `User` object instead of passing `unsafeMetadata` to `update()`. -```ts {{ del: [[1, 5]], ins: [[6, 8]] }} +```ts {{ del: [[1, 6]], ins: [[7, 9]] }} await user.update({ unsafeMetadata: { ...user.unsafeMetadata, diff --git a/docs/guides/development/upgrading/upgrade-guides/core-3.mdx b/docs/guides/development/upgrading/upgrade-guides/core-3.mdx index 23c9117a0c..37041c7e22 100644 --- a/docs/guides/development/upgrading/upgrade-guides/core-3.mdx +++ b/docs/guides/development/upgrading/upgrade-guides/core-3.mdx @@ -568,7 +568,7 @@ The following deprecated APIs have been removed from all Clerk SDKs. ### Frontend {{ toc: false }} - ```ts {{ del: [[1, 5]], ins: [[6, 8]] }} + ```ts {{ del: [[1, 6]], ins: [[7, 9]] }} await user.update({ unsafeMetadata: { ...user.unsafeMetadata, diff --git a/docs/reference/backend/user/update-user-metadata.mdx b/docs/reference/backend/user/update-user-metadata.mdx index ca05180239..0f00eef01f 100644 --- a/docs/reference/backend/user/update-user-metadata.mdx +++ b/docs/reference/backend/user/update-user-metadata.mdx @@ -15,10 +15,10 @@ A "deep" merge will be performed - "deep" means that any nested JSON objects wil Returns a [`User`](/docs/reference/backend/types/backend-user) object. ```ts -function updateUserMetadata(userId: string, params: UpdateUserMetadataParams): Promise +function updateUserMetadata(userId: string, params: UserMetadataParams): Promise ``` -## `UpdateUserMetadataParams` +## `UserMetadataParams` - `userId` diff --git a/docs/reference/native-mobile/user.ios.mdx b/docs/reference/native-mobile/user.ios.mdx index 1189a2c6b4..c54a18a7b7 100644 --- a/docs/reference/native-mobile/user.ios.mdx +++ b/docs/reference/native-mobile/user.ios.mdx @@ -36,7 +36,8 @@ A params overload is also available: let updatedUser = try await user.updateMetadata(.init(unsafeMetadata: ["theme": "dark"])) ``` -> Note: passing `unsafeMetadata` to `user.update(...)` is deprecated. Use `user.updateMetadata(...)` for partial updates going forward. +> [!NOTE] +> Passing `unsafeMetadata` to `user.update(...)` is deprecated. Use `user.updateMetadata(...)` for partial updates going forward. ### Create email address diff --git a/docs/reference/native-mobile/user.mdx b/docs/reference/native-mobile/user.mdx index c9da538199..1387576263 100644 --- a/docs/reference/native-mobile/user.mdx +++ b/docs/reference/native-mobile/user.mdx @@ -42,7 +42,8 @@ val updatedUser = user.updateMetadata( ) ``` -> Note: passing `unsafeMetadata` to `user.update(...)` is deprecated. Use `user.updateMetadata(...)` for partial updates going forward. +> [!NOTE] +> Passing `unsafeMetadata` to `user.update(...)` is deprecated. Use `user.updateMetadata(...)` for partial updates going forward. ### Create email address