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": []
  }
}

A daily cron runs at 02:00 UTC to automatically pull and push for all active federation groups. Manual pull/push is available for immediate sync after configuration changes.

Who can pull and push

Only the group owner may pull or push. A member organization calling either endpoint receives FORBIDDEN (HTTP 403). An organization outside the group receives NOT_FOUND (HTTP 404), the same answer as for a group that does not exist. In both cases nothing is read, written or logged.

Pull, push and the fraud federation push act only on accepted memberships (status: "ACTIVE"). An organization the owner has invited but that has not accepted is skipped by pull-all and bulk push. When you name it as a targetOrgId you get NOT_FOUND (HTTP 404), the same as for an organization outside the group. Nothing is ever written into a tenant that did not consent.

Error responses

Code	Description
`FORBIDDEN`	Not on Enterprise plan, or a member that is not the group owner
`NOT_FOUND`	Group does not exist or you are not in it, or `targetOrgId` is not an accepted member
`PARTIAL_FAILURE`	Some members failed to sync — check the `errors` array