Roles & Capabilities

Simple RBAC model with flat capability strings assigned to roles.

The Simple authorization model assigns flat capability strings directly to roles. Each capability represents a single permission in path:action format.

Capability format

Capabilities follow the pattern path:action, where path is a resource namespace and action is one of six Vault-aligned operations:

Action	Description
read	View a resource
create	Create a new resource
update	Modify an existing resource
delete	Remove a resource
list	List/enumerate resources
sudo	Elevated administrative action

Examples

articles:read
articles:create
orders.refunds:create
settings:sudo

Paths can be nested with dots to express hierarchy (e.g., orders.refunds:create).

System roles vs custom roles

System roles are created by PlatformXe and cannot be modified or deleted. They provide sensible defaults:

Role	Description
super-admin	All capabilities, immutable
viewer	Read-only across all resources

Custom roles are created by your team via the API or Portal. You define the name, description, and capability set.

Creating a role with capabilities

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": "Content Editor",
    "description": "Can manage articles and media",
    "model": "SIMPLE",
    "capabilities": [
      "articles:read",
      "articles:create",
      "articles:update",
      "media:read",
      "media:upload"
    ]
  }'

const role = await px.permissions.createRole({
  name: 'Content Editor',
  description: 'Can manage articles and media',
  model: 'SIMPLE',
  capabilities: [
    'articles:read',
    'articles:create',
    'articles:update',
    'media:read',
    'media:upload',
  ],
});

When to use Simple vs Full model

Use the Simple model when your app has a flat permission structure with a manageable number of capabilities. If your app has discrete modules with their own action sets, use the Full model (Modules & Actions) instead.