Permission Check

API reference for checking and batch-checking permissions.

The permission check endpoint evaluates whether a user is allowed to perform an action, running through the full 4-layer evaluation pipeline (overrides, role capabilities, ABAC conditions, resource policies, ReBAC graph).

Check a single permission

POST /api/v1/permissions/check

Scope: permissions:check

Request body

Field	Type	Required	Description
adminId	string	Yes	The user ID to check permissions for
path	string	Yes	The permission path (e.g., articles, orders.refunds)
action	string	Yes	The action to check (e.g., read, write, delete)
resource	object	No	Resource attributes for ABAC/ReBAC evaluation
context	object	No	Request context for ABAC condition evaluation (e.g., IP, time, custom attributes)

Response

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

Field	Type	Description
allowed	boolean	Whether the action is permitted
source	string	Which evaluation layer produced the decision

Source values

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)

Examples

curl — basic check

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"
  }'

curl — with resource and context

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": "orders",
    "action": "refund",
    "resource": {
      "id": "order_abc123",
      "type": "order",
      "ownerId": "user_xyz789",
      "amount": 50000
    },
    "context": {
      "ip": "102.89.23.45",
      "time": "2026-04-05T14:30:00.000Z",
      "department": "finance"
    }
  }'

SDK — basic check

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

console.log(result.data.allowed); // true
console.log(result.data.source);  // "role"

SDK — with resource and context

const result = await px.permissions.check({
  adminId: 'user_xyz789',
  path: 'orders',
  action: 'refund',
  resource: {
    id: 'order_abc123',
    type: 'order',
    ownerId: 'user_xyz789',
    amount: 50000,
  },
  context: {
    ip: '102.89.23.45',
    time: '2026-04-05T14:30:00.000Z',
    department: 'finance',
  },
});

Batch check

Check up to 100 permissions in a single request. Useful for rendering a UI where you need to know which actions a user can perform across multiple resources.

POST /api/v1/permissions/check-batch

Scope: permissions:check

Request body

Field	Type	Required	Description
adminId	string	Yes	The user ID to check permissions for
checks	Array<{ path: string, action: string, resource?: object }>	Yes	Array of permission checks (max 100)
context	object	No	Shared request context applied to all checks

curl

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

SDK

const result = await px.permissions.checkBatch({
  adminId: 'user_xyz789',
  checks: [
    { path: 'articles', action: 'read' },
    { path: 'articles', action: 'write' },
    { path: 'articles', action: 'delete' },
    { path: 'settings', action: 'manage' },
  ],
});

for (const check of result.data.results) {
  console.log(`${check.path}:${check.action} → ${check.allowed}`);
}

Response

{
  "success": true,
  "data": {
    "results": [
      { "path": "articles", "action": "read", "allowed": true, "source": "role" },
      { "path": "articles", "action": "write", "allowed": true, "source": "role" },
      { "path": "articles", "action": "delete", "allowed": true, "source": "role" },
      { "path": "settings", "action": "manage", "allowed": false, "source": "none" }
    ]
  }
}

Error responses

Code	Description
BAD_REQUEST	Missing required fields or invalid check format
FORBIDDEN	API key does not have the permissions:check scope
RATE_LIMITED	Exceeded 5,000 checks/hr limit