Shadow Check

Compare local permission decisions against PlatformXe for migration validation.

The shadow check endpoint lets you validate your migration by comparing a local permission decision against PlatformXe's evaluation. This is essential during the dual-write phase of migrating to PlatformXe authorization.

Endpoint

POST /api/v1/permissions/shadow-check

Scope: permissions:check

Rate limit: 5,000/hr

Request body

Field	Type	Required	Description
adminId	string	Yes	The user to check
path	string	Yes	Permission path
action	string	Yes	Action to check
localDecision	boolean	Yes	What your local system decided

curl

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

SDK

const result = await px.permissions.shadowCheck({
  adminId: 'user_xyz789',
  path: 'articles',
  action: 'delete',
  localDecision: true,
});

if (result.data.discrepancy) {
  console.warn('Permission mismatch:', {
    local: result.data.localAllowed,
    remote: result.data.remoteAllowed,
  });
}

Response

{
  "success": true,
  "data": {
    "adminId": "user_xyz789",
    "path": "articles",
    "action": "delete",
    "localAllowed": true,
    "remoteAllowed": false,
    "discrepancy": true,
    "remoteSource": "none"
  }
}

Field	Type	Description
localAllowed	boolean	The local decision you provided
remoteAllowed	boolean	PlatformXe's evaluation result
discrepancy	boolean	true if local and remote disagree
remoteSource	string	Which evaluation layer PlatformXe used

Migration workflow

1. Shadow mode — call shadow check on every permission decision, log discrepancies
2. Fix discrepancies — adjust roles, policies, or overrides in PlatformXe until discrepancies reach zero
3. Read cutover — switch your app to read from PlatformXe instead of local
4. Cleanup — remove local permission code

Error responses

Code	Description
BAD_REQUEST	Missing required fields
FORBIDDEN	API key missing permissions:check scope