Federation Groups

Create and manage federation groups for multi-app authorization.

A federation group is a shared authorization namespace owned by a single organization. Other organizations join the group as members.

Scope: permissions:manage

Rate limit: 500/hr

Create a group

POST /api/v1/permissions/federation/groups

Field	Type	Required	Description
name	string	Yes	Group name
description	string	No	Human-readable description

curl -X POST https://api.platformxe.com/api/v1/permissions/federation/groups \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "name": "Caldera Ecosystem",
    "description": "Shared permissions across all Caldera apps"
  }'

const group = await px.permissions.createFederationGroup({
  name: 'Caldera Ecosystem',
  description: 'Shared permissions across all Caldera apps',
});

List groups

GET /api/v1/permissions/federation/groups

Returns all groups the current organization owns or belongs to.

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

Response

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "fed_abc123",
        "name": "Caldera Ecosystem",
        "description": "Shared permissions across all Caldera apps",
        "ownerId": "org_owner456",
        "memberCount": 3,
        "createdAt": "2026-03-01T10:00:00.000Z"
      }
    ]
  }
}

Get group detail

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

Returns the group with its members, modules, and last sync status.

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

Delete a group

DELETE /api/v1/permissions/federation/groups/:id

Only the owning organization can delete a group. Deleting a group removes all member associations and sync state.

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

Error responses

Code	Description
BAD_REQUEST	Missing group name
FORBIDDEN	Not on Enterprise plan, or not the group owner (for delete)
NOT_FOUND	Group ID does not exist