Federation Members

Invite organizations into a federation group, accept invitations, and leave or remove members.

Members are organizations that participate in a federation group. Each member has a unique prefix used to namespace its modules.

Membership needs consent from both sides. The group owner invites an organization, and the invited organization accepts with its own API key. Until it accepts, the membership is INVITED and the owner cannot pull modules from it, push role assignments into it, or push fraud configuration to it.

Scope: permissions:manage

Rate limit: 500/hr

Membership lifecycle

Status	Set by	Pull / push / fraud push
INVITED	Owner calls POST …/members	Skipped. A targeted pull or push returns NOT_FOUND
ACTIVE	Invited organization calls POST …/members/accept	Included

The owner's own membership is ACTIVE from the moment the group is created. Memberships that existed before 2026-09-15 were migrated as ACTIVE.

Invite a member

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

Only the group owner may invite.

Field	Type	Required	Description
organizationId	string	Yes	The org ID to invite
prefix	string	Yes	2-4 uppercase letters, unique within the group

curl -X POST https://api.platformxe.com/api/v1/permissions/federation/groups/fed_abc123/members \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_owner_key" \
  -d '{
    "organizationId": "org_lettings456",
    "prefix": "LT"
  }'

await px.permissions.addFederationMember('fed_abc123', {
  organizationId: 'org_lettings456',
  prefix: 'LT',
});

HTTP 201. The membership starts as INVITED:

{
  "success": true,
  "data": {
    "id": "mem_002",
    "groupId": "fed_abc123",
    "organizationId": "org_lettings456",
    "prefix": "LT",
    "role": "member",
    "status": "INVITED",
    "joinedAt": "2026-09-15T08:00:00.000Z"
  }
}

Prefix rules

• Must be 2-4 uppercase letters (A-Z)
• Must be unique within the group
• Cannot be changed after creation — remove and re-invite to change prefix
• Used in federated keys: LT:BOOKINGS:CREATE

Accept an invitation

POST /api/v1/permissions/federation/groups/:id/members/accept

Call this with the invited organization's own API key. The accepting organization is always the one that owns the key, and any request body is ignored, so no organization can accept on another's behalf. The response is the membership with status: "ACTIVE".

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

Status	Code	When
200	—	Accepted
404	NOT_FOUND	The group does not exist, or your organization holds no invitation to it
409	CONFLICT	The membership is already active

Leave a group, or decline an invitation

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

A member removes its own membership by passing its own organizationId. This works for an INVITED membership (declining) and an ACTIVE one (leaving). The owner cannot leave its own group.

The group owner can also remove any other member with the same call.

organizationId may be sent as a query parameter or in the JSON body.

curl -X DELETE "https://api.platformxe.com/api/v1/permissions/federation/groups/fed_abc123/members?organizationId=org_lettings456" \
  -H "x-api-key: pxk_live_lettings_key"

await px.permissions.removeFederationMember('fed_abc123', 'org_lettings456');

Caller	Target	Result
Any member (invited or active)	Itself	200 — removed
Owner	Another member	200 — removed
Owner	Itself	403 FORBIDDEN — the owner cannot be removed
Owner	An organization outside the group	404 NOT_FOUND — "Organization is not a member of this group"
A member	Another member	403 FORBIDDEN
An organization outside the group	Anyone	404 NOT_FOUND — same answer as for a group that does not exist

Listing members

Members, with their status, are returned as part of the group detail and sync status responses:

{
  "success": true,
  "data": {
    "id": "fed_abc123",
    "name": "Caldera Ecosystem",
    "members": [
      { "id": "mem_001", "organizationId": "org_owner456", "prefix": "OWNER", "role": "owner", "status": "ACTIVE" },
      { "id": "mem_002", "organizationId": "org_lettings456", "prefix": "LT", "role": "member", "status": "ACTIVE" },
      { "id": "mem_003", "organizationId": "org_concierge789", "prefix": "CC", "role": "member", "status": "INVITED" }
    ]
  }
}

Group existence is not disclosed

An organization that is neither the owner nor a member (invited or active) of a group receives NOT_FOUND (HTTP 404) from every group endpoint. That is the same answer as for a group id that does not exist, so group ids cannot be probed. A member that is not the owner receives FORBIDDEN (HTTP 403) for owner-only operations.

Error responses

Code	HTTP	Description
VALIDATION_ERROR	400	Missing organizationId / prefix, or the prefix is not 2-4 uppercase letters
FORBIDDEN	403	Not on Enterprise plan; a member attempting an owner-only operation; removing the owner
NOT_FOUND	404	Group does not exist or you are not in it; no invitation to accept; target organization is not a member
CONFLICT	409	Organization already in the group; prefix already taken; membership already active