Federation

Federation

Instance-to-instance federation allows two CortexPrism instances to establish mutual trust and share resources. Federation uses pairing tokens for initial trust establishment and persists peer metadata in the federation_peers database table.

Architecture

Instance A                              Instance B
┌────────────────┐                      ┌────────────────┐
│ 1. Generate    │                      │                │
│    pairing     │──── pairing_token ──►│ 2. Pair with   │
│    token       │                      │    token        │
│                │◄─── confirmation ────│                │
│                │                      │                │
│ 3. Peer added  │                      │ 3. Peer added  │
│    to peers    │                      │    to peers    │
│    table       │                      │    table       │
└────────────────┘                      └────────────────┘

Pairing Tokens

Pairing tokens are single-use tokens generated by one instance and consumed by another to establish a federation relationship. Tokens follow the format cortex_pair_<uuid> and expire after 1 hour.

Generate a Pairing Token

POST /api/federation/generate-pairing-token
Authorization: Bearer cortex_token_...

Requires instance admin privileges. Stores the token in the config table under pairing_token_<id>.

Response (200):

{
  "id": "pair_550e8400-...",
  "token": "cortex_pair_550e8400-...",
  "expiresIn": "1 hour"
}

Establishing Trust

Pair with a Remote Instance

POST /api/federation/pair
Content-Type: application/json

{
  "endpoint": "http://instance-b:3000",
  "pairing_token": "cortex_pair_550e8400-...",
  "peer_name": "Instance B"
}

Requires instance admin privileges. Creates a record in the federation_peers table.

Field	Required	Description
endpoint	Yes	URL of the remote instance
pairing_token	Yes	Token generated by the remote instance
peer_name	No	Human-readable name (defaults to endpoint)

Response (201):

{
  "id": "peer_550e8400-...",
  "peerName": "Instance B",
  "endpoint": "http://instance-b:3000"
}

Peer Management

List Peers

GET /api/federation/peers
Authorization: Bearer cortex_token_...

Returns all non-revoked peers ordered by pairing date (most recent first).

[
  {
    "id": "peer_abc123",
    "peer_name": "Instance B",
    "endpoint": "http://instance-b:3000",
    "public_key": "pending_verification",
    "paired_at": "2026-06-24T00:00:00Z",
    "revoked_at": null
  }
]

Revoke a Peer

DELETE /api/federation/peers/:id
Authorization: Bearer cortex_token_...

Requires instance admin privileges. Soft-deletes the peer by setting revoked_at.

Response:

{ "ok": true }

Discover Remote Agents

GET /api/federation/peers/:id/agents
Authorization: Bearer cortex_token_...

Returns agents available on the remote peer. Currently returns a pending status as remote agent discovery is under development.

{
  "agents": [],
  "note": "Remote agent discovery pending"
}

Database Table

The federation_peers table (migration 044):

Column	Type	Description
id	TEXT	peer_<uuid> — peer identifier
peer_name	TEXT	Human-readable name
endpoint	TEXT	Remote instance URL
public_key	TEXT	Public key for verification (defaults to pending_verification)
paired_at	TEXT	ISO 8601 pairing timestamp
revoked_at	TEXT	ISO 8601 revocation timestamp (null = active)

API Summary

Method	Path	Auth	Description
POST	/api/federation/generate-pairing-token	Instance Admin	Generate a 1-hour pairing token
POST	/api/federation/pair	Instance Admin	Pair with a remote instance
GET	/api/federation/peers	Authenticated	List all non-revoked peers
DELETE	/api/federation/peers/:id	Instance Admin	Revoke a peer relationship
GET	/api/federation/peers/:id/agents	Authenticated	List remote agents (pending)

Security

• Pairing tokens are single-use with a 1-hour TTL
• Only instance admins can generate pairing tokens, pair instances, and revoke peers
• Peer public keys are stored as pending_verification — future versions will implement proper PKI-based mutual authentication
• Revoked peers are soft-deleted (timestamps preserved for audit trail)

See Also

• Multi-User Collaboration — Users, teams, and authorization
• Swarm — Cross-instance agent coordination
• API Tokens — Token-based authentication for API access
• Security Model — Parallax security architecture