Update Custom Role

Overview

Update an existing custom role in the client Platform - change its display name, description, permissions, or metadata.

The role slug is not updated by this endpoint (see success response - slug stays sales-manager). That keeps user assignments stable after rename.

When to use this endpoint?

Use Update Custom Role when:

An admin renames a role or edits its description in Platform → Custom Roles.
You add or remove permission keys for a desk or team role.
You update Platform UI hints in metadata (for example badge color).
You save changes from a role edit form after Get Custom Role.

Part of the client Platform Custom Roles module. Prefer not to update system roles (isSystem: true) from the UI.

Editable Fields

Fields accepted in the PATCH body. slug is not editable here.

Field	Type	Required	Description
name	string	Optional	Updated display name shown in the Platform UI.
description	string	Optional	Updated summary of what this role is for.
permissions	string[]	Optional	Full replacement list of permission keys for this role.
metadata	object	Optional	Updated metadata map (for example color).

PATCH{baseUrl}/api/{apiVersion}/user-role/:roleId

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

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.
Content-Type	application/json	JSON request body.

Path Parameters

Parameter	Example	Description
roleId	66b0f1a2c3d4e5f6a7b8c9d0	The role's `_id`. Get it from List or Get Custom Role.

Request Payload

Example updating name, description, permissions, and metadata. Do not send slug - it stays unchanged.

json

1{2  "name": "Senior Sales Manager",3  "description": "Updated description",4  "permissions": [5    "chat.read",6    "chat.assign",7    "chat.export"8  ],9  "metadata": {10    "color": "#16a34a"11  }12}

Success Response (HTTP 200 OK)

On success, the API returns the updated role. Note that slug is unchanged.

json

1{2  "success": true,3  "message": "Role updated successfully",4  "data": {5    "_id": "66b0f...8c9d0",6    "name": "Senior Sales Manager",7    "slug": "sales-manager",8    "description": "Updated description",9    "permissions": [10      "chat.read",11      "chat.assign",12      "chat.export"13    ],14    "isDefault": false,15    "isSystem": false,16    "metadata": {17      "color": "#16a34a"18    },19    "createdAt": "2026-06-23T10:00:00.000Z",20    "updatedAt": "2026-06-23T11:00:00.000Z"21  },22  "error": null23}

Common Errors

Update fails when the token lacks admin access, the role is missing, or the body is invalid.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Role missing

json

1{2  "success": false,3  "message": "Entity not found",4  "data": null,5  "error": "Entity not found"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Custom Roles.
404 Not Found	No role exists for the given `roleId`.
400 Bad Request	Empty or invalid update body.
500 Internal Server Error	An unexpected error occurred while updating the role.

Best Practices

Treat permissions as a full replacement list - send every key you want after the update.
Never change how you assign users: keep using the original slug even after a rename.
Block edits for isSystem roles in the Platform UI unless your policy allows it.
Always send tenant headers with a client Bearer token over HTTPS.

Role updated

Refresh the Custom Roles table from the returned document, or reload with Get Custom Role / List.

Update Custom Role

Overview

Update an existing custom role in the client Platform - change its display name, description, permissions, or metadata.

The role slug is not updated by this endpoint (see success response - slug stays sales-manager). That keeps user assignments stable after rename.

When to use this endpoint?

Use Update Custom Role when:

An admin renames a role or edits its description in Platform → Custom Roles.
You add or remove permission keys for a desk or team role.
You update Platform UI hints in metadata (for example badge color).
You save changes from a role edit form after Get Custom Role.

Part of the client Platform Custom Roles module. Prefer not to update system roles (isSystem: true) from the UI.

Editable Fields

Fields accepted in the PATCH body. slug is not editable here.

Field	Type	Required	Description
name	string	Optional	Updated display name shown in the Platform UI.
description	string	Optional	Updated summary of what this role is for.
permissions	string[]	Optional	Full replacement list of permission keys for this role.
metadata	object	Optional	Updated metadata map (for example color).

PATCH{baseUrl}/api/{apiVersion}/user-role/:roleId

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

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.
Content-Type	application/json	JSON request body.

Path Parameters

Parameter	Example	Description
roleId	66b0f1a2c3d4e5f6a7b8c9d0	The role's `_id`. Get it from List or Get Custom Role.

Request Payload

Example updating name, description, permissions, and metadata. Do not send slug - it stays unchanged.

json

1{2  "name": "Senior Sales Manager",3  "description": "Updated description",4  "permissions": [5    "chat.read",6    "chat.assign",7    "chat.export"8  ],9  "metadata": {10    "color": "#16a34a"11  }12}

Success Response (HTTP 200 OK)

On success, the API returns the updated role. Note that slug is unchanged.

json

1{2  "success": true,3  "message": "Role updated successfully",4  "data": {5    "_id": "66b0f...8c9d0",6    "name": "Senior Sales Manager",7    "slug": "sales-manager",8    "description": "Updated description",9    "permissions": [10      "chat.read",11      "chat.assign",12      "chat.export"13    ],14    "isDefault": false,15    "isSystem": false,16    "metadata": {17      "color": "#16a34a"18    },19    "createdAt": "2026-06-23T10:00:00.000Z",20    "updatedAt": "2026-06-23T11:00:00.000Z"21  },22  "error": null23}

Common Errors

Update fails when the token lacks admin access, the role is missing, or the body is invalid.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Role missing

json

1{2  "success": false,3  "message": "Entity not found",4  "data": null,5  "error": "Entity not found"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Custom Roles.
404 Not Found	No role exists for the given `roleId`.
400 Bad Request	Empty or invalid update body.
500 Internal Server Error	An unexpected error occurred while updating the role.

Best Practices

Treat permissions as a full replacement list - send every key you want after the update.
Never change how you assign users: keep using the original slug even after a rename.
Block edits for isSystem roles in the Platform UI unless your policy allows it.
Always send tenant headers with a client Bearer token over HTTPS.

Role updated

Refresh the Custom Roles table from the returned document, or reload with Get Custom Role / List.