Create Custom Role

Overview

Create a custom role for your tenant in the client Platform. Custom roles let you define named permission sets (for example Sales Manager) beyond the built-in system roles such as Admin and User.

Each role has a stable slug (used when assigning users), a human-readable name, optional description, permission keys, and optional metadata (for example a badge color in the Platform UI).

When to use this endpoint?

Use Create Custom Role when:

An admin adds a new role from Platform → Custom Roles.
You need department- or desk-specific permission sets (sales, support, and so on).
You want a reusable slug to assign via Platform → Users → Update.
You store UI hints (color, icon) in metadata for the roles table.

Part of the client Platform Custom Roles module. Requires a client Access Token with tenant admin privileges - not a chat end-user token.

Workflow

1
Define the role
In the Platform Custom Roles screen, choose a display name, unique slug, description, and permission keys.
2
Create the role
POST the payload with tenant headers and a client Access Token. The API returns the new role document.
3
Save the slug
Use data.slug when assigning roles to users (Platform → Users → Update uses the role slug).
4
Assign to users
Update tenant users with the new slug so they receive the intended permissions in your product.

Request Fields

Field	Type	Required	Description
name	string	Required	Display name shown in the Platform UI (for example `Sales Manager`).
slug	string	Required	Unique machine-friendly id (for example `sales-manager`). Used when assigning the role to users. Prefer lowercase kebab-case.
description	string	Optional	Short explanation of what this role is for.
permissions	string[]	Optional	Permission keys granted by this role (for example `chat.read`, `chat.assign`).
metadata	object	Optional	Extra attributes for your Platform UI (color, labels, and so on).

POST{baseUrl}/api/{apiVersion}/user-role/create

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.

Request Payload

Example creating a Sales Manager role with two permission keys and a UI color in metadata:

json

1{2  "name": "Sales Manager",3  "slug": "sales-manager",4  "description": "Manages the sales desk",5  "permissions": [6    "chat.read",7    "chat.assign"8  ],9  "metadata": {10    "color": "#3b82f6"11  }12}

Success Response (HTTP 201 Created)

On success, the API returns the created role. isSystem and isDefault are typically false for custom roles.

json

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

Common Errors

Create fails when the token lacks admin access, the slug already exists, or required fields are missing.

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 400 Bad Request - Duplicate slug

json

1{2  "success": false,3  "message": "Role slug already exists",4  "data": null,5  "error": "Role slug already exists"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Custom Roles.
400 Bad Request	Missing `name` / `slug`, or slug already exists.
500 Internal Server Error	An unexpected error occurred while creating the role.

Best Practices

Keep slugs stable after create - users are assigned by slug, and update does not change it.
Use clear permission keys your product already understands; empty permissions means no extra grants beyond defaults.
Prefer kebab-case slugs (sales-manager) so they match user update payloads.
Always send tenant headers with a client Bearer token over HTTPS.

Role created

Open the role in your Custom Roles list, then assign slug to users under Platform → Users → Update.

Create Custom Role

Overview

Create a custom role for your tenant in the client Platform. Custom roles let you define named permission sets (for example Sales Manager) beyond the built-in system roles such as Admin and User.

Each role has a stable slug (used when assigning users), a human-readable name, optional description, permission keys, and optional metadata (for example a badge color in the Platform UI).

When to use this endpoint?

Use Create Custom Role when:

An admin adds a new role from Platform → Custom Roles.
You need department- or desk-specific permission sets (sales, support, and so on).
You want a reusable slug to assign via Platform → Users → Update.
You store UI hints (color, icon) in metadata for the roles table.

Part of the client Platform Custom Roles module. Requires a client Access Token with tenant admin privileges - not a chat end-user token.

Workflow

1
Define the role
In the Platform Custom Roles screen, choose a display name, unique slug, description, and permission keys.
2
Create the role
POST the payload with tenant headers and a client Access Token. The API returns the new role document.
3
Save the slug
Use data.slug when assigning roles to users (Platform → Users → Update uses the role slug).
4
Assign to users
Update tenant users with the new slug so they receive the intended permissions in your product.

Request Fields

Field	Type	Required	Description
name	string	Required	Display name shown in the Platform UI (for example `Sales Manager`).
slug	string	Required	Unique machine-friendly id (for example `sales-manager`). Used when assigning the role to users. Prefer lowercase kebab-case.
description	string	Optional	Short explanation of what this role is for.
permissions	string[]	Optional	Permission keys granted by this role (for example `chat.read`, `chat.assign`).
metadata	object	Optional	Extra attributes for your Platform UI (color, labels, and so on).

POST{baseUrl}/api/{apiVersion}/user-role/create

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.

Request Payload

Example creating a Sales Manager role with two permission keys and a UI color in metadata:

json

1{2  "name": "Sales Manager",3  "slug": "sales-manager",4  "description": "Manages the sales desk",5  "permissions": [6    "chat.read",7    "chat.assign"8  ],9  "metadata": {10    "color": "#3b82f6"11  }12}

Success Response (HTTP 201 Created)

On success, the API returns the created role. isSystem and isDefault are typically false for custom roles.

json

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

Common Errors

Create fails when the token lacks admin access, the slug already exists, or required fields are missing.

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 400 Bad Request - Duplicate slug

json

1{2  "success": false,3  "message": "Role slug already exists",4  "data": null,5  "error": "Role slug already exists"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Custom Roles.
400 Bad Request	Missing `name` / `slug`, or slug already exists.
500 Internal Server Error	An unexpected error occurred while creating the role.

Best Practices

Keep slugs stable after create - users are assigned by slug, and update does not change it.
Use clear permission keys your product already understands; empty permissions means no extra grants beyond defaults.
Prefer kebab-case slugs (sales-manager) so they match user update payloads.
Always send tenant headers with a client Bearer token over HTTPS.

Role created

Open the role in your Custom Roles list, then assign slug to users under Platform → Users → Update.

Define the role

Create the role

Save the slug

Assign to users

HTTP 401 Unauthorized - No token

HTTP 403 Forbidden - Tenant admin required

HTTP 400 Bad Request - Duplicate slug

Role created

Define the role

Create the role

Save the slug

Assign to users

HTTP 401 Unauthorized - No token

HTTP 403 Forbidden - Tenant admin required

HTTP 400 Bad Request - Duplicate slug

Role created