Overrides API

Create, list, and remove per-user permission overrides.

Admin overrides grant or deny specific permissions for individual users, bypassing role evaluation.

Scope: permissions:manage

Rate limit: 500/hr

Create an override

POST /api/v1/permissions/overrides

Field	Type	Required	Description
`adminId`	`string`	Yes	User ID to override
`path`	`string`	Yes	Permission path
`action`	`string`	Yes	Action to override
`effect`	`string`	Yes	`GRANT` or `DENY`
`reason`	`string`	Yes	Reason for override (min 10 chars)
`expiresAt`	`string`	No	ISO 8601 UTC expiry timestamp

curl -X POST https://api.platformxe.com/api/v1/permissions/overrides \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "adminId": "user_xyz789",
    "path": "billing",
    "action": "delete",
    "effect": "DENY",
    "reason": "Temporary block during financial audit period",
    "expiresAt": "2026-06-01T00:00:00.000Z"
  }'

await px.permissions.createOverride({
  adminId: 'user_xyz789',
  path: 'billing',
  action: 'delete',
  effect: 'DENY',
  reason: 'Temporary block during financial audit period',
  expiresAt: '2026-06-01T00:00:00.000Z',
});

List overrides for a user

GET /api/v1/permissions/overrides/:adminId

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

const overrides = await px.permissions.listOverrides('user_xyz789');

Response

{
  "success": true,
  "data": {
    "overrides": [
      {
        "id": "ovr_abc123",
        "adminId": "user_xyz789",
        "path": "billing",
        "action": "delete",
        "effect": "DENY",
        "reason": "Temporary block during financial audit period",
        "expiresAt": "2026-06-01T00:00:00.000Z",
        "createdAt": "2026-04-01T10:00:00.000Z"
      }
    ]
  }
}

Delete an override

DELETE /api/v1/permissions/overrides/remove/:id

curl -X DELETE https://api.platformxe.com/api/v1/permissions/overrides/remove/ovr_abc123 \
  -H "x-api-key: pxk_live_your_api_key_here"

await px.permissions.deleteOverride('ovr_abc123');

Overrides with an expiresAt timestamp are automatically excluded from evaluation after expiry. You do not need to delete expired overrides — they are cleaned up during the 90-day audit retention cron.

Error responses

Code	Description
`BAD_REQUEST`	Missing required fields, reason too short, or invalid effect
`NOT_FOUND`	Override ID does not exist
`FORBIDDEN`	API key missing `permissions:manage` scope