Update User Metadata

Update organization-scoped metadata for a specific user

This endpoint requires organization admin privileges. Only users with the org:admin role can update user metadata.

Organization-Scoped Metadata: Metadata set through this endpoint is specific to the user’s membership in your organization. If the same user belongs to multiple organizations, each organization maintains separate metadata.

Update custom metadata for a user within your organization. Perfect for managing user roles, departments, teams, or any custom properties needed for filtering and organization.

Authentication

Authorization · string · required

Bearer token for authentication. Must be from a user with org:admin role.

Body

userId · string · required

Clerk user ID of the user whose metadata should be updated

metadata · object · required

Key-value pairs of metadata to set for the user. This completely replaces existing metadata.

Show Common Metadata Fields

• role: User’s role or job title (e.g., “manager”, “developer”)
• department: Department name (e.g., “engineering”, “marketing”)
• team: Team assignment (e.g., “backend”, “frontend”)
• level: Seniority level (e.g., “senior”, “junior”)
• vnum: Vendor or employee number
• Custom fields: Any key-value pairs relevant to your organization

Response

success · boolean

Whether the metadata update was successful

user · object

Updated user information

Show User Object

id · string

Clerk user ID

email · string

User’s email address

firstName · string

User’s first name

lastName · string

User’s last name

publicMetadata · object

The updated organization-scoped metadata

Examples

Basic Update

curl -X POST https://asteragents.com/api/admin/updateUserMetadata \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_2ABC123DEF",
    "metadata": {
      "role": "senior-developer",
      "department": "engineering",
      "team": "backend"
    }
  }'

Error Codes

400 · object

Bad Request - Invalid request data or validation errors

401 · object

Unauthorized - Invalid or missing authentication

403 · object

Forbidden - User is not an admin in the organization, or target user is not a member of the organization

405 · object

Method Not Allowed - Only POST requests are accepted

500 · object

Internal Server Error - Unexpected error occurred

Use Cases

Department Management

Assign users to departments for organizational filtering:

await fetch('/api/admin/updateUserMetadata', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({
    userId: 'user_123',
    metadata: {
      department: 'marketing',
      role: 'content-writer',
      team: 'social-media'
    }
  })
});

Role-Based Access Control

Set roles that can be used for filtering in the dashboard:

# Promote user to manager
requests.post('/api/admin/updateUserMetadata',
    headers=headers,
    json={
        'userId': 'user_456',
        'metadata': {
            'role': 'manager',
            'department': 'engineering',
            'level': 'senior',
            'manages_team': 'backend'
        }
    })

Custom Properties

Store any custom data relevant to your organization:

// Track contractor information
await fetch('/api/admin/updateUserMetadata', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({
    userId: 'user_789',
    metadata: {
      employment_type: 'contractor',
      contract_end_date: '2024-12-31',
      hourly_rate: 'tier-3',
      vnum: 'CON-9876'
    }
  })
});

Workflow

Step 1: Get User ID

First, retrieve the user ID from the Get Organization Users endpoint:

const usersResponse = await fetch('/api/admin/getUsersInOrg', {
  headers: { 'Authorization': 'Bearer ' + token }
});
const users = await usersResponse.json();

// Find the user you want to update
const targetUser = users.find(u => u.email === '[e-mail]');

Step 2: Update Metadata

Then update their metadata:

await fetch('/api/admin/updateUserMetadata', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: targetUser.id,
    metadata: {
      role: 'senior-developer',
      department: 'engineering'
    }
  })
});

Features

Organization Isolation: Complete metadata separation between organizations.

• Per-Organization Metadata: Same user in different orgs has independent metadata
• Complete Replacement: Metadata object completely replaces existing metadata (not merged)
• Real-time Updates: Changes are immediately reflected in dashboard filters and user listings
• Flexible Schema: Store any JSON-serializable data structure
• Dashboard Integration: Use metadata for filtering conversations and statistics

Important Notes

Metadata Replacement: This endpoint completely replaces the user’s metadata in your organization. To preserve existing fields, fetch current metadata first and merge your changes before updating.

• Metadata is scoped to the organization - each org maintains separate metadata for shared users
• Removing a user from the organization deletes their metadata for that org
• Re-adding a user creates fresh metadata (previous metadata is not restored)
• Metadata can contain any JSON-serializable data (strings, numbers, booleans, objects, arrays)
• Changes are reflected immediately in dashboard filters

Security Notes

• Only organization admins can update user metadata
• Target user must be a member of your organization
• Cannot update metadata for users in other organizations
• Metadata is visible in API responses to all org members

Use this endpoint with Get Organization Users to build powerful user management workflows and custom dashboards.