Create Role
Create a new role with specific permissions for your workspace.
Requires the role:create permission in the workspace.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Request Body
namestringrequiredName of the role (e.g., "Agent Manager").
descriptionstringrequiredDescription of the role and its intended use. Must not be empty.
permissionsarray of stringsrequiredPermission keys to grant, in category:action form (e.g., "agent:view", "call_history:view"). At least one is required. Each item must be a plain string, not an object. An unknown key returns 400 with Invalid permission: <key>. agency_hub:* permissions can only be granted in an agency (white-label) master workspace; elsewhere they return 403. Use List Permissions for the available keys.
userIdsarray of stringsrequiredUser IDs to assign this role to. Send an empty array [] to create the role without assigning anyone.
Response
Returns 201 Created with the new role.
_idstringUnique identifier for the created role.
namestringName of the role.
descriptionstringDescription of the role.
permissionsobjectGranted permissions grouped by category. Each key is a category and its value is the list of permission keys in that category.
workspaceIdstringWorkspace ID associated with the role.
isSystembooleanAlways false for roles you create.
createdAtstringTimestamp when the role was created.
updatedAtstringTimestamp when the role was last updated.
{
"name": "Manager",
"description": "Full access to agents and call history",
"permissions": [
"agent:view",
"agent:create",
"agent:edit",
"call_history:view"
],
"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
}{
"error": "Invalid permission: agent_view"
}Last updated on