Create Role

Create a new role with specific permissions for your workspace.

POST /v1/api/roles-and-permissions/roles

With permissions

{
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": [
    "agent_view",
    "agent_create",
    "agent_edit",
    "call_history_view"
  ]
}

{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": [
    { "key": "agent_view", "category": "agents" },
    { "key": "agent_create", "category": "agents" },
    { "key": "agent_edit", "category": "agents" },
    { "key": "call_history_view", "category": "calls" }
  ],
  "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
  "createdAt": "2024-06-01T09:00:00.000Z"
}

Headers

x-api-key · string · required

API key used for authenticating requests to the API.

x-workspace-id · string · required

Workspace identifier for the API.

Request Body

name · string · required

Name of the role (e.g., “Agent Manager”, “Viewer”).

description · string

Description of the role and its intended use.

permissions · array of strings · required

Array of permission ID strings to assign to this role. Always required — pass an empty array [] if no permissions are needed. Each item must be a plain string (e.g., "agent_view"), not an object. Use the List Permissions endpoint to retrieve available permission IDs.

userIds · array

Array of user IDs to assign this role to.

Response Fields

_id · string

Unique identifier for the created role.

name · string

Name of the role.

description · string

Description of the role.

permissions · array

Array of permission objects assigned to the role.

workspaceId · string

Workspace ID associated with the role.

createdAt · string

Timestamp when the role was created.

With permissions

{
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": [
    "agent_view",
    "agent_create",
    "agent_edit",
    "call_history_view"
  ]
}

{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": [
    { "key": "agent_view", "category": "agents" },
    { "key": "agent_create", "category": "agents" },
    { "key": "agent_edit", "category": "agents" },
    { "key": "call_history_view", "category": "calls" }
  ],
  "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
  "createdAt": "2024-06-01T09:00:00.000Z"
}