Roles

Caution

Role management endpoints require the roles:read, roles:write, or roles:delete permission. There is no separate create/update action — creating and editing both use roles:write.

Overview

Manage roles and permissions within your organization. Roles are collections of permissions that can be assigned to users.

List Permissions

Get all available permissions in the system.

GET /api/permissions

Response

{
  "status": "success",
  "data": {
    "permissions": [
      {
        "id": "uuid",
        "resource": "users",
        "action": "read",
        "description": "View users"
      },
      {
        "id": "uuid",
        "resource": "users",
        "action": "write",
        "description": "Create and edit users"
      }
    ]
  }
}

List Roles

Get all roles in your organization.

GET /api/roles

Note

Requires roles:read permission.

Query Parameters

Parameter	Type	Description
search	string	Filter by role name

Response

{
  "status": "success",
  "data": {
    "roles": [
      {
        "id": "uuid",
        "name": "admin",
        "description": "Full access to all features",
        "is_system": true,
        "is_default": false,
        "permissions": ["users:read", "users:write", "users:delete"],
        "user_count": 3,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "uuid",
        "name": "Custom Role",
        "description": "Custom role with specific permissions",
        "is_system": false,
        "is_default": false,
        "permissions": ["chat:read", "chat:write"],
        "user_count": 8,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 4,
    "page": 1,
    "limit": 50
  }
}

permissions is a flat array of resource:action strings, and user_count is how many users hold the role. There is no permission_count field.

Get Role

Get a single role with its permissions.

GET /api/roles/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Custom Role",
    "description": "Custom role with specific permissions",
    "is_system": false,
    "is_default": false,
    "permissions": [
      {
        "id": "uuid",
        "resource": "contacts",
        "action": "read",
        "description": "View contacts"
      },
      {
        "id": "uuid",
        "resource": "contacts",
        "action": "write",
        "description": "Create and edit contacts"
      }
    ],
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Create Role

Create a new custom role.

POST /api/roles

Note

Requires roles:write permission.

Request Body

{
  "name": "Support Agent",
  "description": "Can view and respond to chats",
  "permissions": ["contacts:read", "chat:read", "chat:write"]
}

Field	Type	Required	Description
name	string	Yes	Unique role name
description	string	No	Role description
permissions	array	Yes	Array of permission keys (e.g., resource:action)
is_default	boolean	No	Set as default role for new users

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Support Agent",
    "description": "Can view and respond to chats",
    "is_system": false,
    "is_default": false,
    "permissions": [
      {
        "id": "uuid",
        "resource": "contacts",
        "action": "read",
        "description": "View contacts"
      }
    ],
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update Role

Update an existing custom role.

PUT /api/roles/{id}

Note

Requires roles:write permission.

Caution

System roles (admin, manager, agent) cannot be modified.

Request Body

{
  "name": "Senior Support Agent",
  "description": "Can view, respond to chats, and access analytics",
  "permissions": ["contacts:read", "chat:read", "chat:write", "analytics:read"]
}

Field	Type	Description
name	string	Role name
description	string	Role description
permissions	array	Array of permission keys
is_default	boolean	Set as default role for new users

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Senior Support Agent",
    "description": "Can view, respond to chats, and access analytics",
    "is_system": false,
    "is_default": false,
    "permissions": [...],
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Delete Role

Delete a custom role.

DELETE /api/roles/{id}

Note

Requires roles:delete permission.

Caution

• System roles cannot be deleted
• Roles with assigned users cannot be deleted (reassign users first)

Response

{
  "status": "success",
  "data": {
    "message": "Role deleted successfully"
  }
}

Permission Keys

Permissions use the format resource:action. The only valid actions are: read, write, delete, sync, execute, import, export, pickup, and assign.

Caution

There is no create or update action. Creating and editing both map to write.

The full catalog below matches the permissions seeded on every organization.

Users, Roles & Teams

• users:read, users:write, users:delete
• roles:read, roles:write, roles:delete
• teams:read, teams:write, teams:delete

Settings

• settings.general:read, settings.general:write
• settings.chatbot:read, settings.chatbot:write
• settings.sso:read, settings.sso:write

WhatsApp Accounts, Templates & Flows

• accounts:read, accounts:write, accounts:delete
• templates:read, templates:write, templates:delete, templates:sync
• flows.whatsapp:read, flows.whatsapp:write, flows.whatsapp:delete
• flows.chatbot:read, flows.chatbot:write, flows.chatbot:delete

Chatbot

• chatbot.keywords:read, chatbot.keywords:write, chatbot.keywords:delete
• chatbot.ai:read, chatbot.ai:write, chatbot.ai:delete

Chat & Contacts

• chat:read, chat:write, chat.assign:write
• contacts:read, contacts:write, contacts:delete, contacts:import, contacts:export
• tags:read, tags:write, tags:delete
• transfers:read, transfers:write, transfers:pickup
• canned_responses:read, canned_responses:write, canned_responses:delete

Campaigns

• campaigns:read, campaigns:write, campaigns:delete, campaigns:execute

Analytics & Audit

• analytics:read, analytics:write, analytics:delete, analytics.agents:read
• audit_logs:read

Integrations

• webhooks:read, webhooks:write, webhooks:delete
• api_keys:read, api_keys:write, api_keys:delete
• custom_actions:read, custom_actions:write, custom_actions:delete

Organizations

• organizations:read, organizations:write, organizations:delete, organizations:assign

Calling

• call_logs:read
• ivr_flows:read, ivr_flows:write, ivr_flows:delete
• call_transfers:read, call_transfers:write
• outgoing_calls:read, outgoing_calls:write

See Also

• Roles & Permissions - Learn about the permission system
• Users API - User management