Roles & Permissions

Manage custom roles and inspect the permission catalog that powers Replicer's role-based access control (RBAC).

Dashboard endpoints

These endpoints are served by the Replicer dashboard under /api/roles and are authenticated with your dashboard session (the auth_token cookie), not with a /v1 API key. Access is governed by RBAC permissions rather than API-key scopes. Organization owners implicitly hold every permission.

Every mutating endpoint requires the roles.manage permission. Listing roles is also available to holders of team.manage (so team managers can assign roles).

---

List roles

GET /api/roles

Retrieve all roles for the current organization, ordered with system roles first.

Required permission: roles.manage or team.manage

Response 200 OK

{
  "success": true,
  "roles": [
    {
      "id": "clx-role-001",
      "name": "Administrator",
      "description": "Full access to all organization features",
      "permissions": ["agents.manage", "team.manage", "roles.manage"],
      "isSystem": true,
      "memberCount": 3,
      "invitationCount": 0,
      "createdAt": "2026-03-01T10:00:00Z",
      "updatedAt": "2026-03-01T10:00:00Z"
    }
  ]
}

memberCount is the number of distinct users assigned to the role (a user is counted once even if the role is both their organization role and their active role). invitationCount is the number of pending invitations for the role.

---

List available permissions

GET /api/roles/permissions

Return the full permission catalog and the groups used to render the role editor. Readable by any authenticated user.

Required permission: none (authentication only)

Response 200 OK

{
  "success": true,
  "permissions": [
    "agents.manage",
    "calls.create",
    "campaigns.create",
    "campaigns.start",
    "team.manage",
    "roles.manage"
  ],
  "groups": [
    { "id": "ai", "permissions": ["agents.manage", "knowledge.manage", "tts.manage"] },
    { "id": "organization", "permissions": ["billing.manage", "team.manage", "roles.manage"] }
  ]
}

---

Create a role

POST /api/roles

Create a custom role for the organization.

Required permission: roles.manage

Request body

Field	Type	Required	Description
name	string	Yes	Unique role name (1–64 characters)
description	string	No	Optional description (max 256 characters)
permissions	string[]	Yes	At least one permission key from the catalog

Example

curl -X POST https://replicer.ai/api/roles \
  -H "Content-Type: application/json" \
  --cookie "auth_token=your_session_token" \
  -d '{
    "name": "Support Agent",
    "description": "Can manage agents and create calls",
    "permissions": ["agents.manage", "calls.create"]
  }'

Response 200 OK

{
  "success": true,
  "role": {
    "id": "clx-role-010",
    "name": "Support Agent",
    "description": "Can manage agents and create calls",
    "permissions": ["agents.manage", "calls.create"],
    "isSystem": false,
    "organizationId": "clx-org-001",
    "createdAt": "2026-04-05T10:00:00Z",
    "updatedAt": "2026-04-05T10:00:00Z"
  }
}

Errors

Status	When
400	Invalid permission key, or a role with the same name already exists
403	Missing the roles.manage permission

---

Update a role

PATCH /api/roles/:id

Update a role's name, description, or permissions. All fields are optional; only the provided fields are changed.

Required permission: roles.manage

Request body

Field	Type	Required	Description
name	string	No	New unique name (1–64 characters)
description	string | null	No	New description (max 256 characters)
permissions	string[]	No	Replacement permission list (min 1 entry)

Response 200 OK

{
  "success": true,
  "role": {
    "id": "clx-role-010",
    "name": "Support Agent",
    "description": "Updated description",
    "permissions": ["agents.manage", "calls.create", "campaigns.create"],
    "isSystem": false,
    "organizationId": "clx-org-001",
    "createdAt": "2026-04-05T10:00:00Z",
    "updatedAt": "2026-04-06T09:00:00Z"
  }
}

Errors

Status	When
400	Invalid permission key, duplicate name, or removing roles.manage from the last role that has it
403	Missing the roles.manage permission
404	Role not found in this organization

---

Delete a role

DELETE /api/roles/:id

Delete a custom role.

Required permission: roles.manage

Response 200 OK

{
  "success": true
}

Errors

Status	When
400	System roles cannot be deleted, the role is still assigned to members or invitations, or it is the last role with roles.manage
403	Missing the roles.manage permission
404	Role not found in this organization