API Reference
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). |
{baseUrl}/api/{apiVersion}/user-role/:roleIdAuthentication
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.
{
"name": "Senior Sales Manager",
"description": "Updated description",
"permissions": [
"chat.read",
"chat.assign",
"chat.export"
],
"metadata": {
"color": "#16a34a"
}
}Success Response (HTTP 200 OK)
On success, the API returns the updated role. Note that slug is unchanged.
{
"success": true,
"message": "Role updated successfully",
"data": {
"_id": "66b0f...8c9d0",
"name": "Senior Sales Manager",
"slug": "sales-manager",
"description": "Updated description",
"permissions": [
"chat.read",
"chat.assign",
"chat.export"
],
"isDefault": false,
"isSystem": false,
"metadata": {
"color": "#16a34a"
},
"createdAt": "2026-06-23T10:00:00.000Z",
"updatedAt": "2026-06-23T11:00:00.000Z"
},
"error": null
}Common Errors
Update fails when the token lacks admin access, the role is missing, or the body is invalid.
HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 403 Forbidden — Tenant admin required
{
"success": false,
"message": "Access denied: tenant admin privileges required",
"data": null,
"error": null
}HTTP 404 Not Found — Role missing
{
"success": false,
"message": "Entity not found",
"data": null,
"error": "Entity not found"
}| 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
permissionsas a full replacement list — send every key you want after the update. - Never change how you assign users: keep using the original
slugeven after a rename. - Block edits for
isSystemroles 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.