Roles

CRUD operations for managing authorization roles.

Roles are the primary unit of access control. Each role uses either the Simple (capabilities) or Full (modules) model.

Scope: permissions:manage

Rate limit: 500/hr

List roles

GET /api/v1/permissions/roles

curl https://api.platformxe.com/api/v1/permissions/roles \
  -H "x-api-key: pxk_live_your_api_key_here"

const roles = await px.permissions.listRoles();

Create a role

POST /api/v1/permissions/roles

Field	Type	Required	Description
name	string	Yes	Unique role name
description	string	No	Human-readable description
model	string	Yes	SIMPLE or FULL

curl -X POST https://api.platformxe.com/api/v1/permissions/roles \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "name": "Support Agent",
    "description": "Read-only access to tickets and users",
    "model": "SIMPLE"
  }'

const role = await px.permissions.createRole({
  name: 'Support Agent',
  description: 'Read-only access to tickets and users',
  model: 'SIMPLE',
});

Get a role

GET /api/v1/permissions/roles/:id

Returns the role with its capabilities (Simple model) or module permissions (Full model).

curl https://api.platformxe.com/api/v1/permissions/roles/role_abc123 \
  -H "x-api-key: pxk_live_your_api_key_here"

Update a role

PATCH /api/v1/permissions/roles/:id

curl -X PATCH https://api.platformxe.com/api/v1/permissions/roles/role_abc123 \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "description": "Updated description for support agents"
  }'

Delete a role

DELETE /api/v1/permissions/roles/:id

curl -X DELETE https://api.platformxe.com/api/v1/permissions/roles/role_abc123 \
  -H "x-api-key: pxk_live_your_api_key_here"

Error responses

Code	Description
BAD_REQUEST	Invalid model type or missing name
CONFLICT	Role with that name already exists
FORBIDDEN	API key missing permissions:manage scope, or attempting to modify a system role
NOT_FOUND	Role ID does not exist