Create Custom Role

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).

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.

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

{
  "name": "Sales Manager",
  "slug": "sales-manager",
  "description": "Manages the sales desk",
  "permissions": [
    "chat.read",
    "chat.assign"
  ],
  "metadata": {
    "color": "#3b82f6"
  }
}

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

{
  "success": true,
  "message": "Role created successfully",
  "data": {
    "_id": "66b0...c9d0",
    "name": "Sales Manager",
    "slug": "sales-manager",
    "description": "Manages the sales desk",
    "permissions": [
      "chat.read",
      "chat.assign"
    ],
    "isDefault": false,
    "isSystem": false,
    "metadata": {
      "color": "#3b82f6"
    },
    "createdAt": "2026-06-23T10:00:00.000Z",
    "updatedAt": "2026-06-23T10:00:00.000Z"
  },
  "error": null
}

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

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

{
  "success": false,
  "message": "Access denied: tenant admin privileges required",
  "data": null,
  "error": null
}

{
  "success": false,
  "message": "Role slug already exists",
  "data": null,
  "error": "Role slug already exists"
}

• 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.