Update User

Partially update a tenant user’s profile in the client workspace. This endpoint supports independent updates — you can change a single field or several fields in one request.

Only these request payload fields can be updated:

• name
• email
• role
• isActive
• metadata

Other user properties (online status, last seen, and similar) are not editable through this endpoint. On success, the API returns the updated user document so your UI can refresh without an extra fetch.

Use Update User when:

• An admin renames a user (name only).
• You need to change a user’s email (email only).
• You assign or change a tenant role slug (role only).
• You activate or deactivate a user (isActive only).
• Custom metadata keys need to be added or updated for filtering (metadata only).

At least one editable field must be present in the request body. Send only the fields you want to change — unsupported fields are ignored.

The table below lists every field this endpoint accepts. Each field can be updated on its own (single-field update) or combined with others.

All fields above are optional individually, but the body must include at least one of them.

Because this endpoint is partial, each editable value can be updated independently. Use these patterns when your UI changes one setting at a time.

{
  "name": "Will Smith"
}

{
  "email": "will.smith@example.com"
}

{
  "role": "moderator"
}

{
  "isActive": false
}

{
  "metadata": {
    "department": "support"
  }
}

Example combining multiple editable fields in one request. You do not need to send every field — omit anything you are not changing.

{
  "name": "Will Smith",
  "email": "will.smith@example.com",
  "role": "moderator",
  "isActive": true,
  "metadata": {
    "workspaceId": "c1"
  }
}

When the update succeeds, the API returns the updated user document with the new field values merged in.

{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "_id": "699f...645d",
    "name": "Will Smith",
    "email": "will.smith@example.com",
    "role": "moderator",
    "isActive": true,
    "isOnline": false,
    "profileImage": "https://example.com/profile-image.png",
    "metadata": {
      "workspaceId": "c1"
    },
    "lastSeen": "2026-07-09T10:58:31.000Z",
    "createdAt": "2026-05-14T08:22:10.000Z",
    "updatedAt": "2026-07-09T11:30:00.000Z",
    "__v": 4
  },
  "error": null
}

Updates fail when the email conflicts, the role is invalid, nothing editable is provided, or authentication is missing.

{
  "success": false,
  "message": "Invalid role",
  "data": null,
  "error": "Invalid role"
}

{
  "success": false,
  "message": "Email already in use by another user",
  "data": null,
  "error": "Email already in use by another user"
}

• Prefer single-field updates when the UI edits one control at a time (name, email, role, active status, or metadata).
• Never send an empty body — always include at least one of name, email, role, isActive, or metadata.
• Validate email uniqueness in the UI when possible to avoid 409 Conflict.
• Assign only role slugs that exist for the tenant to avoid 400 Bad Request.
• Keep metadata keys consistent so list filters with metadata.<key> remain reliable.
• Always set Content-Type: application/json with tenant headers and a Bearer token.