PATCH/organizations/{organization_id}/memberships/{user_id}/metadata

Merge and update organization membership metadata

Update an organization membership's metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep merge. 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.

IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 2 body fields

organization_idstringrequired

The ID of the organization to which this membership belongs

user_idstringrequired

The ID of the user to which this membership belongs

public_metadataobjectoptional

Metadata saved on the organization membership, that is visible to both your frontend and backend. The new object will be merged with the existing value.

private_metadataobjectoptional

Metadata saved on the organization membership that is only visible to your backend. The new object will be merged with the existing value.

4 status codes

200Success

idstringrequired

objectstringrequired

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

Allowed:organization_membership

rolestringrequired

role_namestringoptional

permissionsarray<string>required

public_metadataobjectrequired

Metadata saved on the organization membership, accessible from both Frontend and Backend APIs

private_metadataobjectoptional

Metadata saved on the organization membership, accessible only from the Backend API

organizationobjectrequired

public_user_dataobjectoptional

An organization membership with public user data populated

created_atintegerrequired

Unix timestamp of creation.

updated_atintegerrequired

Unix timestamp of last update.

400Request was not successful

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

404Resource not found

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

422Invalid request parameters

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.

import { Client } from "@octridev/clerk";

const client = new Client({
  baseUrl: "https://api.clerk.com/v1",
  auth: { bearer: process.env.API_TOKEN },
});

const result = await client.metadata.update({
  organizationId: "9b2f1c10-7a3e-4d54-8c2a-1f6b9e0d4a21",
  userId: "c0a80123-4567-89ab-cdef-0123456789ab",
  publicMetadata: {},
  privateMetadata: {},
});

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "organization_membership",
  "role": "administrator",
  "role_name": "Example Name",
  "permissions": [
    "example_value"
  ],
  "organization": {
    "object": "organization",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Name",
    "slug": "my-example-resource",
    "image_url": "https://example.com",
    "has_image": true,
    "members_count": 42,
    "missing_member_with_elevated_permissions": true,
    "pending_invitations_count": 42,
    "max_allowed_memberships": 1,
    "admin_delete_enabled": true,
    "self_serve_sso_enabled": true,
    "self_serve_directory_sync_enabled": true,
    "created_by": "example_value",
    "created_at": 1,
    "updated_at": "2026-01-15T09:00:00Z",
    "last_active_at": 1,
    "role_set_key": "example_key_abc123"
  },
  "public_user_data": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Example Name",
    "last_name": "Example Name",
    "profile_image_url": "https://example.com",
    "image_url": "https://example.com",
    "has_image": true,
    "identifier": "example_value",
    "username": "janedoe",
    "banned": true,
    "deprovisioned": true
  },
  "created_at": 1,
  "updated_at": "2026-01-15T09:00:00Z"
}

Request

Response

Errors