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 the permission catalog for the active organization. It lists only permissions of components the workspace has (plus the governance permissions every workspace has); platform permissions are never listed. Each entry includes key, module and module_label (the section of the component the permission belongs to), available (always true; kept for older clients) and grantable (whether you hold it and can give it), in addition to its resource and action.

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,
        "version": 4,
        "feature_version": 7,
        "permissions": ["users:read", "users:write", "users:delete"],
        "inactive_permission_count": 0,
        "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,
        "version": 2,
        "feature_version": 7,
        "permissions": ["chat:read", "chat:write"],
        "inactive_permission_count": 1,
        "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 on the workspace’s components, and user_count is how many users hold the role in this organization. Responses include the current version, the workspace’s feature_version, and inactive_permission_count: saved grants on components the workspace doesn’t have, which aren’t listed and give no access. 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,
    "version": 1,
    "feature_version": 7,
    "permissions": ["contacts:read", "contacts:write"],
    "inactive_permission_count": 0,
    "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,
    "version": 1,
    "feature_version": 7,
    "permissions": ["contacts:read", "chat:read", "chat:write"],
    "inactive_permission_count": 0,
    "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 role names and default flags are fixed. Only platform super administrators can edit their permission grants; authorized role administrators can edit descriptions.

Request Body

{
  "name": "Senior Support Agent",
  "version": 1,
  "feature_version": 7,
  "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
version	integer	Required current version from the role response; stale edits return 409
feature_version	integer	feature_version from the role response. Required when sending any permissions value (including []) or remove_inactive_permissions: true; 400 without it. Optional for metadata-only saves. A save that sends a stale feature_version (the workspace’s components changed since) returns 409
remove_inactive_permissions	boolean	Removes the role’s saved grants on components the workspace doesn’t have. You must hold each one; platform grants are never removed

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,
    "version": 2,
    "feature_version": 7,
    "permissions": [...],
    "inactive_permission_count": 0,
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Omitting permissions preserves the current grants. permissions is the role’s grants on the workspace’s components: sending an empty array clears those. Grants on components the workspace doesn’t have (and platform grants) aren’t listed and are kept as saved; they give no access until the component is added, unless you send remove_inactive_permissions: true. Unknown keys are rejected, and new grants on components the workspace doesn’t have return 403. Editors can only grant or remove permissions they hold among the listed ones; a saved grant on a missing component doesn’t stop them editing the rest. Metadata and grants save atomically. A tenant administrator cannot edit their own role, and changes cannot remove an organization’s last active administrator.

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.calling:read, settings.calling:write
• settings.chatbot:read, settings.chatbot:write
• chatbot.routing:read, chatbot.routing:write
• chatbot.hours:read, chatbot.hours:write
• chatbot.sla:read, chatbot.sla:write

WhatsApp Accounts, Templates & Flows

• accounts:read, accounts:write, accounts:delete
• catalogs:read, catalogs:write, catalogs: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
• chatbot.memory:read, chatbot.memory:write

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, tags:import, tags:export
• 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:assign (tenant member visibility and assignment)

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

Platform SSO, organization creation, WhatsApp app and webhook-inbox administration require a platform super administrator. Legacy settings.sso and organization write/delete grants are reserved and cannot be delegated through tenant roles.

See Also

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