Pull & Push

Synchronize modules and permissions across federation members.

The pull and push operations keep federation groups in sync. Pull fetches module definitions from member apps. Push sends resolved permissions to member apps.

Scope: permissions:manage

Rate limit: 500/hr

Pull modules

POST /api/v1/permissions/federation/groups/:id/pull

Fetches the latest module definitions from all member apps and merges them into the federation namespace with prefixed keys.

curl -X POST https://api.platformxe.com/api/v1/permissions/federation/groups/fed_abc123/pull \
  -H "x-api-key: pxk_live_your_api_key_here"

const result = await px.permissions.federationPull('fed_abc123');
console.log(result.data.modules);
// ['LT:BOOKINGS', 'LT:PROPERTIES', 'CC:TASKS', 'CC:CONTACTS']

Response

{
  "success": true,
  "data": {
    "modules": [
      { "key": "LT:BOOKINGS", "actions": ["READ", "CREATE", "UPDATE", "DELETE"] },
      { "key": "CC:TASKS", "actions": ["READ", "CREATE", "ASSIGN", "COMPLETE"] }
    ],
    "pulledAt": "2026-04-05T14:30:00.000Z"
  }
}

Push permissions

POST /api/v1/permissions/federation/groups/:id/push

Sends the resolved permission set — which roles have which actions on which modules — to all member apps.

curl -X POST https://api.platformxe.com/api/v1/permissions/federation/groups/fed_abc123/push \
  -H "x-api-key: pxk_live_your_api_key_here"

const result = await px.permissions.federationPush('fed_abc123');
console.log(result.data.pushedTo);
// ['org_lettings456', 'org_concierge789']

Response

{
  "success": true,
  "data": {
    "pushedTo": ["org_lettings456", "org_concierge789"],
    "pushedAt": "2026-04-05T14:31:00.000Z"
  }
}

Sync status

GET /api/v1/permissions/federation/groups/:id/status

Check the last pull and push timestamps and any sync errors.

curl https://api.platformxe.com/api/v1/permissions/federation/groups/fed_abc123/status \
  -H "x-api-key: pxk_live_your_api_key_here"

Response

{
  "success": true,
  "data": {
    "lastPull": "2026-04-05T02:00:00.000Z",
    "lastPush": "2026-04-05T02:01:00.000Z",
    "nextScheduledSync": "2026-04-06T02:00:00.000Z",
    "errors": []
  }
}

Error responses

Code	Description
FORBIDDEN	Not on Enterprise plan or not the group owner
NOT_FOUND	Group does not exist
PARTIAL_FAILURE	Some members failed to sync — check the errors array