Update User

Update an existing user's profile fields.

PATCH /api/v1/users/{id}
Authentication
Bearer Token
Version
v1
Section
Users
Tags
users write

Updates one or more fields of an existing user. This is a partial update (PATCH semantics) — only the fields included in the request body are modified; omitted fields retain their current values.

Immutable Fields

The following fields cannot be changed after creation:

  • id — system-assigned, globally unique
  • createdAt — set at creation time

Email Uniqueness

If you update email, the new address must not be in use by any other user in your organization. A 409 Conflict is returned otherwise.

Path Parameters * required

NameTypeRequiredDescription
id*string✓The unique identifier of the user (e.g. usr_abc123).

Request Headers

HeaderTypeRequiredDescription
Authorization*string✓Bearer token. Format: Bearer <token>. Requires users:write scope.
Content-Type*string✓Must be application/json.

Request Body

Content-Type: application/json

All fields are optional. Only provided fields will be updated.

{
  "name": "Alice Smith",
  "role": "admin",
  "metadata": { "department": "engineering" }
}
FieldTypeRequiredDescription
namestring—Full display name of the user.
emailstring—Primary email address. Must be unique within the organization.
rolestring—User role. Allowed values: member, admin, viewer.
metadataobject—Arbitrary key-value pairs for application use. Max 16 keys.

Responses

StatusDescription
200User updated successfully. Returns the updated user object.
{
  "id": "usr_abc123",
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-06-01T08:00:00Z"
}
400Validation error. Check the errors array for field details.
401Unauthorized. Missing or invalid token.
403Forbidden. Token does not have users:write scope.
404User not found.
409Conflict. The new email address is already used by another user.

Examples

curl -X PATCH "https://api.example.com/v1/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Smith", "role": "admin"}'

const updated = await fetch('/api/v1/users/usr_abc123', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Alice Smith', role: 'admin' }),
}).then(r => r.json());
console.log(updated.updatedAt);

import requests

r = requests.patch(
    'https://api.example.com/v1/users/usr_abc123',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={'name': 'Alice Smith', 'role': 'admin'}
)
print(r.json()['updatedAt'])