Authorization Quick Start

Create a role, assign capabilities, and check a permission in 3 steps.

This guide walks you through setting up basic RBAC with PlatformXe's Authorization Engine. By the end, you will have a role with capabilities and a working permission check.

Step 1: Create a role

Create a role that will hold a set of capabilities.

curl

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": "editor",
    "description": "Can read and write articles",
    "type": "simple"
  }'

SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const role = await px.permissions.roles.create({
  name: 'editor',
  description: 'Can read and write articles',
  type: 'simple',
});

console.log(role.data.id);
// "role_abc123"

Response

{
  "success": true,
  "data": {
    "id": "role_abc123",
    "name": "editor",
    "description": "Can read and write articles",
    "type": "simple",
    "createdAt": "2026-04-05T10:00:00.000Z"
  }
}

Step 2: Assign capabilities to the role

Add capabilities that define what the role can do.

curl

curl -X POST 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": [
      { "path": "articles", "action": "read" },
      { "path": "articles", "action": "write" },
      { "path": "articles", "action": "delete" }
    ]
  }'

SDK

await px.permissions.roles.addCapabilities('role_abc123', {
  capabilities: [
    { path: 'articles', action: 'read' },
    { path: 'articles', action: 'write' },
    { path: 'articles', action: 'delete' },
  ],
});

Step 3: Check a permission

Check whether a user with the editor role can read articles.

curl

curl -X POST https://api.platformxe.com/api/v1/permissions/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "adminId": "user_xyz789",
    "path": "articles",
    "action": "read"
  }'

SDK

const result = await px.permissions.check({
  adminId: 'user_xyz789',
  path: 'articles',
  action: 'read',
});

if (result.data.allowed) {
  console.log('Access granted via:', result.data.source);
  // "role"
} else {
  console.log('Access denied');
}

Response

{
  "success": true,
  "data": {
    "allowed": true,
    "source": "role"
  }
}

The source field tells you which layer of the evaluation pipeline granted access:

Source	Description
role	Granted by a role capability
override_grant	Granted by an admin override
override_deny	Denied by an admin override
policy_grant	Granted by a resource policy
policy_deny	Denied by a resource policy
rebac	Granted by a ReBAC relationship
none	No matching rule found (defaults to deny)

Next steps

• Permission Check API — batch checks, resource context, and ABAC conditions
• Authorization Overview — understand the full 4-layer evaluation pipeline