Update User

Overview

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.

When to use this endpoint?

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.

Editable Fields

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

Field	Type	Required	Description
name	string	Optional	Display name of the user. Can be sent alone to rename the user.
email	string	Optional	Email address for the user. Must be unique within the tenant. Returns 409 Conflict if already used by another user.
role	string	Optional	Tenant role slug (for example `user`, `moderator`, `admin`). Must be a valid role for the tenant or the API returns 400 Bad Request.
isActive	boolean	Optional	Whether the user account is active. Send alone to activate or deactivate without changing other fields.
metadata	object	Optional	Custom key/value data (for example department or team). Send alone to update metadata without changing profile fields.

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

Single-Field Updates

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

Update name only

json

1{2  "name": "Will Smith"3}

Update email only

json

1{2  "email": "will.smith@example.com"3}

Update role only

json

1{2  "role": "moderator"3}

Update active status only

json

1{2  "isActive": false3}

Update metadata only

json

1{2  "metadata": {3    "department": "support"4  }5}

PATCH{baseUrl}/api/{apiVersion}/client/users/:userId

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Access Token from Login Client or Register Client.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Uses the {{clientId}} variable.
Content-Type	application/json	Required when sending a JSON request body.

Path Parameters

Parameter	Example	Description
userId	string	User _id (24-char Mongo ObjectId) of the user to update.

Request Payload

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

json

1{2  "name": "Will Smith",3  "email": "will.smith@example.com",4  "role": "moderator",5  "isActive": true,6  "metadata": {7    "workspaceId": "c1"8  }9}

Success Response (HTTP 200 OK)

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

json

1{2  "success": true,3  "message": "User updated successfully",4  "data": {5    "_id": "699f...645d",6    "name": "Will Smith",7    "email": "will.smith@example.com",8    "role": "moderator",9    "isActive": true,10    "isOnline": false,11    "profileImage": "https://example.com/profile-image.png",12    "metadata": {13      "workspaceId": "c1"14    },15    "lastSeen": "2026-07-09T10:58:31.000Z",16    "createdAt": "2026-05-14T08:22:10.000Z",17    "updatedAt": "2026-07-09T11:30:00.000Z",18    "__v": 419  },20  "error": null21}

Common Errors

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

HTTP 400 Bad Request - Invalid role

json

1{2  "success": false,3  "message": "Invalid role",4  "data": null,5  "error": "Invalid role"6}

HTTP 409 Conflict - Email already in use

json

1{2  "success": false,3  "message": "Email already in use by another user",4  "data": null,5  "error": "Email already in use by another user"6}

Code	Reason
400 Bad Request	Invalid role, invalid field values, or no editable fields provided.
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	User not found for the given `userId`.
409 Conflict	Email already in use by another user.
500 Internal Server Error	An unexpected error occurred while updating the user.

Best Practices

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.

User updated

Refresh your list or detail view with the returned document, or call Get User Detail again if other screens cache an older copy.

Update User

Overview

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

When to use this endpoint?

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.

Editable Fields

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

Field	Type	Required	Description
name	string	Optional	Display name of the user. Can be sent alone to rename the user.
email	string	Optional	Email address for the user. Must be unique within the tenant. Returns 409 Conflict if already used by another user.
role	string	Optional	Tenant role slug (for example `user`, `moderator`, `admin`). Must be a valid role for the tenant or the API returns 400 Bad Request.
isActive	boolean	Optional	Whether the user account is active. Send alone to activate or deactivate without changing other fields.
metadata	object	Optional	Custom key/value data (for example department or team). Send alone to update metadata without changing profile fields.

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

Single-Field Updates

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

Update name only

json

1{2  "name": "Will Smith"3}

Update email only

json

1{2  "email": "will.smith@example.com"3}

Update role only

json

1{2  "role": "moderator"3}

Update active status only

json

1{2  "isActive": false3}

Update metadata only

json

1{2  "metadata": {3    "department": "support"4  }5}

PATCH{baseUrl}/api/{apiVersion}/client/users/:userId

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Access Token from Login Client or Register Client.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Uses the {{clientId}} variable.
Content-Type	application/json	Required when sending a JSON request body.

Path Parameters

Parameter	Example	Description
userId	string	User _id (24-char Mongo ObjectId) of the user to update.

Request Payload

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

json

1{2  "name": "Will Smith",3  "email": "will.smith@example.com",4  "role": "moderator",5  "isActive": true,6  "metadata": {7    "workspaceId": "c1"8  }9}

Success Response (HTTP 200 OK)

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

json

1{2  "success": true,3  "message": "User updated successfully",4  "data": {5    "_id": "699f...645d",6    "name": "Will Smith",7    "email": "will.smith@example.com",8    "role": "moderator",9    "isActive": true,10    "isOnline": false,11    "profileImage": "https://example.com/profile-image.png",12    "metadata": {13      "workspaceId": "c1"14    },15    "lastSeen": "2026-07-09T10:58:31.000Z",16    "createdAt": "2026-05-14T08:22:10.000Z",17    "updatedAt": "2026-07-09T11:30:00.000Z",18    "__v": 419  },20  "error": null21}

Common Errors

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

HTTP 400 Bad Request - Invalid role

json

1{2  "success": false,3  "message": "Invalid role",4  "data": null,5  "error": "Invalid role"6}

HTTP 409 Conflict - Email already in use

json

1{2  "success": false,3  "message": "Email already in use by another user",4  "data": null,5  "error": "Email already in use by another user"6}

Code	Reason
400 Bad Request	Invalid role, invalid field values, or no editable fields provided.
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	User not found for the given `userId`.
409 Conflict	Email already in use by another user.
500 Internal Server Error	An unexpected error occurred while updating the user.

Best Practices

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.

User updated

Refresh your list or detail view with the returned document, or call Get User Detail again if other screens cache an older copy.