Capabilities

Manage capability strings on Simple-model roles.

Capabilities are flat permission strings in path:action format, assigned to roles using the Simple model.

Scope: permissions:manage

Rate limit: 500/hr

List capabilities

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

Returns all capability strings assigned to a role.

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

const caps = await px.permissions.listCapabilities('role_abc123');
// ['articles:read', 'articles:create', 'media:read']

Response

{
  "success": true,
  "data": {
    "roleId": "role_abc123",
    "capabilities": [
      "articles:read",
      "articles:create",
      "articles:update",
      "media:read"
    ]
  }
}

Replace capabilities

PUT /api/v1/permissions/roles/:id/capabilities

Replaces the entire capability set for a role. This is a full replacement — any capabilities not included in the request are removed.

Field	Type	Required	Description
`capabilities`	`string[]`	Yes	Full list of capabilities in `path:action` format

curl -X PUT https://api.platformxe.com/api/v1/permissions/roles/role_abc123/capabilities \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "capabilities": [
      "articles:read",
      "articles:create",
      "articles:update",
      "articles:delete",
      "media:read",
      "media:upload"
    ]
  }'

await px.permissions.setCapabilities('role_abc123', {
  capabilities: [
    'articles:read',
    'articles:create',
    'articles:update',
    'articles:delete',
    'media:read',
    'media:upload',
  ],
});

This is a full replacement operation. To add a single capability, first fetch the current list, append the new capability, and send the complete list.

Validation

Capabilities must match the path:action format. Invalid formats return a BAD_REQUEST error:

articles:read — valid
orders.refunds:create — valid (nested paths allowed)
articles — invalid (missing action)
:read — invalid (missing path)

Error responses

Code	Description
`BAD_REQUEST`	Capability does not match `path:action` format
`NOT_FOUND`	Role ID does not exist in the API key's organization. Roles belonging to another organization are reported as not found (HTTP 404) for both GET and PUT
`FORBIDDEN`	API key missing `permissions:manage` scope