Enable federation with a peer

You're an admin on your-host.example.com and you want to peer with peer.acme.com. Both must agree.

1. Verify your /.well-known#

Hit your own descriptor first to make sure it's correct:

1

curl https://your-host.example.com/.well-known/scaiwave/server | jq .

Should look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "server_name": "your-host.example.com",
  "public_key": "ed25519:base64...",
  "protocol_versions": ["v1"],
  "endpoints": {
    "send": "/_scaiwave/federation/v1/send",
    "profile": "/_scaiwave/federation/v1/profile/{local_id}",
    "members": "/_scaiwave/federation/v1/rooms/{room_id}/members",
    "backfill": "/_scaiwave/federation/v1/rooms/{room_id}/backfill"
  }
}

If this doesn't load: check that:

• SCAIWAVE_SERVER_NAME matches the host name.
• TLS is valid (peers verify cert chains by default).
• A federation key is provisioned. If public_key is empty, run scaiwave admin federation key generate.

2. Check the peer's descriptor#

1

curl https://peer.acme.com/.well-known/scaiwave/server | jq .

If the peer doesn't publish one, federation isn't possible.

3. Update your federation policy#

1
2
3
4
5
6
7
8

curl -X PUT "https://your-host.example.com/v1/admin/federation/policy" \
  -H "Authorization: Bearer $ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_mode": "invite_only",
    "allowed_peers": ["peer.acme.com"],
    "max_foreign_participants_per_room": 50
  }'

default_mode options:

• open — accept federation invites from any peer.
• invite_only — only accept invites where the peer is in allowed_peers.
• closed — refuse all federation.

4. Have the peer reciprocate#

The peer's admin runs the same setup pointed at your server. Both sides need each other's descriptor; both sides need each other in their respective allowed_peers lists (if either is in invite_only mode).

5. Test with a federated DM#

1
2
3
4

curl -X POST "https://your-host.example.com/v1/me/federated-dms" \
  -H "Authorization: Bearer $YOUR_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fqid": "@alice:peer.acme.com"}'

If this succeeds, the foreign user gets the invite in their notification panel. When they accept, the DM is operational.

6. Backfill#

If you want history to flow from the peer (e.g. you joined an already-existing room), the federation backfill endpoint pulls it:

1
2

curl -X POST "https://your-host.example.com/v1/admin/rooms/$ROOM_ID/federation/backfill" \
  -H "Authorization: Bearer $ADMIN"

Pulls up to 1000 historical events from the peer's /_scaiwave/federation/v1/rooms/{room_id}/backfill endpoint. Each event is signature-verified before storage.

7. Monitor#

GET /v1/admin/federation/peers returns the active peer set with last_seen and last_error columns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "data": [
    {
      "server_name": "peer.acme.com",
      "last_seen": "2026-05-17T13:00:00Z",
      "last_error": null,
      "events_sent_24h": 142,
      "events_received_24h": 87
    }
  ]
}

If last_error is set, traffic is failing. Common causes:

• Their /.well-known returns a different public key than what you cached → key rotation. Refresh with POST /v1/admin/federation/foreign/{participant_id}/refresh.
• Their server is down → wait.
• Signature mismatch → check that both sides are on the same protocol version.

8. Rotate your federation key#

Federation keys rotate yearly. To rotate manually:

1

scaiwave admin federation key rotate

Generates a new keypair, publishes the new public key on /.well-known, and starts signing new events with it. Peers auto-discover the new key on next event verification (with a 30-day overlap window where both keys are accepted).

What can't be federated#

• Incognito rooms.
• Bridge rooms.
• Rooms with room_type=sidekick.
• Rooms whose owner tenant has federation disabled tenant-wide.

The federation endpoint refuses these with clear error codes.

Where to go next#

• Concepts: Federation.
• API: Federation.
• Join a federated room — user-side.