Trillet AI logo

Create Role

Create a new role with specific permissions for your workspace.

POSThttps://api.trillet.ai/v1/api/roles-and-permissions/roles

Requires the role:create permission in the workspace.

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

namestringrequired

Name of the role (e.g., "Agent Manager").

descriptionstringrequired

Description of the role and its intended use. Must not be empty.

permissionsarray of stringsrequired

Permission 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 stringsrequired

User 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.

_idstring

Unique identifier for the created role.

namestring

Name of the role.

descriptionstring

Description of the role.

permissionsobject

Granted permissions grouped by category. Each key is a category and its value is the list of permission keys in that category.

workspaceIdstring

Workspace ID associated with the role.

isSystemboolean

Always false for roles you create.

createdAtstring

Timestamp when the role was created.

updatedAtstring

Timestamp 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": []
}
201
{
  "_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
}
400
{
  "error": "Invalid permission: agent_view"
}

Last updated on