List Roles
Retrieve all roles available in your workspace, including the built-in system roles.
Requires the role:view permission in the workspace.
The response is a bare array. It contains the workspace's custom roles plus the four built-in system roles, owner, admin, editor and viewer (lowercase, isSystem: true). System roles have no workspaceId.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Response Fields
_idstringUnique identifier for the role.
namestringName of the role.
descriptionstringDescription of the role.
permissionsobjectPermissions grouped by category. Each key is a category and its value is the list of permission keys (e.g., "agent": ["agent:view", "agent:edit"]).
isSystembooleantrue for the built-in roles, which can't be edited or deleted.
workspaceIdstringWorkspace the role belongs to. Absent on system roles.
userIdsarray of stringsIDs of the users in this workspace who hold the role.
createdAtstringTimestamp when the role was created.
updatedAtstringTimestamp when the role was last updated.
[
{
"_id": "c8c8c8c8c8c8c8c8c8c8c8c8",
"name": "editor",
"description": "Can edit content and users but not billing or subscriptions.",
"permissions": {
"agent": ["agent:create", "agent:view", "agent:edit", "agent:delete"],
"call_history": ["call_history:view"]
},
"isSystem": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z",
"__v": 0,
"userIds": []
},
{
"_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
"workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1",
"name": "Manager",
"description": "Full access to agents and call history",
"permissions": {
"agent": ["agent:view", "agent:create", "agent:edit"],
"call_history": ["call_history:view"]
},
"isSystem": false,
"createdAt": "2024-06-01T09:00:00.000Z",
"updatedAt": "2024-06-01T09:00:00.000Z",
"__v": 0,
"userIds": ["a8a8a8a8a8a8a8a8a8a8a8a8"]
}
]Last updated on