Skip to main content
POST
https://asteragents.com/api
/
admin
/
updateUserMetadata
Update User Metadata
curl --request POST \
  --url https://asteragents.com/api/admin/updateUserMetadata \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "metadata": {}
}
'
{
  "400": {},
  "401": {},
  "403": {},
  "405": {},
  "500": {},
  "success": true,
  "user": {
    "id": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "publicMetadata": {}
  }
}
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.

​
Response

​
success
boolean
Whether the metadata update was successful
​
user
object
Updated user information

​
Examples

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 === '[email protected]');

​
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.