API Reference

List Custom Roles

Overview

Retrieve a paginated list of roles for your tenant — both built-in system roles (Admin, User) and custom roles you created in the client Platform.

Use this endpoint to power the Custom Roles table, role pickers when editing users, and search for roles by name or slug.

When to use this endpoint?

Use List Custom Roles when:

Loading Platform → Custom Roles for the admin roles table.
Filling a role dropdown when creating or updating a Platform user.
Searching roles by name or slug with pagination.
Distinguishing system roles (isSystem: true) from custom ones before allowing edit or delete.

Part of the client Platform Custom Roles module. Requires a client Access Token with tenant admin privileges.

Response Data

Each item in data.list typically includes:

Field	Description
_id	Role document id — use with Get / Update / Delete by id.
name	Display name in the Platform UI.
slug	Stable slug assigned to users (`role` field on user update).
permissions	Permission keys. `"*"` often means full access on system Admin.
isSystem / isDefault	Flags for built-in roles. System roles should not be deleted from the Platform UI.
metadata	Optional UI or product attributes (for example color).

GET{baseUrl}/api/{apiVersion}/user-role/list?search=&page=1&limit=10

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.

Query Parameters

Parameter	Required	Example	Description
search	Optional	—	Case-insensitive text search (regex-escaped). Matches searchable fields such as name and slug.
page	Optional	1	Page number, 1-based. Default 1.
limit	Optional	10	Page size — items per page. Default 10.

Success Response (HTTP 200 OK)

On success, the API returns list and pagination. The example includes system Admin / User plus one custom role.

json

{
  "success": true,
  "message": "Role list fetched successfully",
  "data": {
    "list": [
      {
        "_id": "66bp...0001",
        "name": "Admin",
        "slug": "admin",
        "description": "Full tenant administrator",
        "permissions": [
          "*"
        ],
        "isDefault": true,
        "isSystem": true,
        "metadata": {},
        "createdAt": "2026-06-22T05:40:02.000Z",
        "updatedAt": "2026-06-22T05:40:02.000Z"
      },
      {
        "_id": "66b0...0002",
        "name": "User",
        "slug": "user",
        "description": "Standard chat user",
        "permissions": [],
        "isDefault": true,
        "isSystem": true,
        "metadata": {},
        "createdAt": "2026-06-22T05:40:02.000Z",
        "updatedAt": "2026-06-22T05:40:02.000Z"
      },
      {
        "_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"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 3,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "pageSize": 10
    }
  },
  "error": null
}

Common Errors

List fails when the token is missing or lacks tenant admin access.

HTTP 401 Unauthorized — No token

json

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

HTTP 403 Forbidden — Tenant admin required

json

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

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Custom Roles.
500 Internal Server Error	An unexpected error occurred while listing roles.

Best Practices

Hide or disable Delete for rows where isSystem is true.
Cache the list briefly for role pickers; refresh after Create / Update / Delete.
Use slug (not _id) when assigning a role on a user.
Always send tenant headers with a client Bearer token over HTTPS.

Roles list ready

Bind the list to your Custom Roles table, then open a row with Get by ID or start Create for a new custom role.

Field

Description

_id

Role document id — use with Get / Update / Delete by id.

name

Display name in the Platform UI.

slug

Stable slug assigned to users (role field on user update).

permissions

Permission keys. "*" often means full access on system Admin.

isSystem / isDefault

Flags for built-in roles. System roles should not be deleted from the Platform UI.

metadata

Optional UI or product attributes (for example color).

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

Tenant (client) id. Required when is-tenant=true.

Parameter

Required

Example

Description

Optional

—

Case-insensitive text search (regex-escaped). Matches searchable fields such as name and slug.

page

Optional

Page number, 1-based. Default 1.

limit

Optional

Page size — items per page. Default 10.

{ "success": true, "message": "Role list fetched successfully", "data": { "list": [ { "_id": "66bp...0001", "name": "Admin", "slug": "admin", "description": "Full tenant administrator", "permissions": [ "*" ], "isDefault": true, "isSystem": true, "metadata": {}, "createdAt": "2026-06-22T05:40:02.000Z", "updatedAt": "2026-06-22T05:40:02.000Z" }, { "_id": "66b0...0002", "name": "User", "slug": "user", "description": "Standard chat user", "permissions": [], "isDefault": true, "isSystem": true, "metadata": {}, "createdAt": "2026-06-22T05:40:02.000Z", "updatedAt": "2026-06-22T05:40:02.000Z" }, { "_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" } ], "pagination": { "currentPage": 1, "totalCount": 3, "hasNextPage": false, "hasPreviousPage": false, "pageSize": 10 } }, "error": null }

Code

Reason

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

Tenant admin privileges required for Platform Custom Roles.

500 Internal Server Error

An unexpected error occurred while listing roles.