Federation

Federation lets two ScaiWave tenants (or two separately-hosted ScaiWave servers entirely) host a shared room. Participants on either side join the room as full members — they can see messages, send replies, react, and get notifications — without giving up tenant isolation on either end.

The model#

• Each server has a long-lived Ed25519 keypair (rotated yearly).
• Each server publishes a well-known descriptor at /.well-known/scaiwave/server with its public key, supported protocol versions, and federation endpoint URL.
• When tenant A invites a participant on tenant B into a room, A's server signs the invite with its private key and POSTs it to B's federation endpoint. B verifies the signature, looks up its local participant, and decides whether to accept.
• Once accepted, every event flowing between A and B is signed with the originating server's key. The receiving side verifies before storing.

The whole protocol is built around:

• Signed events — replay-resistant, tamper-evident.
• Idempotency — every event has a UUID; replays are no-ops.
• Per-room state — federation is per-room, not per-tenant. Two tenants can be in one room together without being "federated globally".

What you see as a user#

Foreign participants appear in the member list with an @local_id:server_name identifier instead of a bare @local_id. Their messages stream in just like local ones. You can @mention them and they get notified on their home server.

The chat header in a federated room shows a 🌐 badge.

What admins see#

Admins see the active set of peer servers their tenant has talked to (/v1/admin/federation/peers), the federation policy (/v1/admin/federation/policy — controls auto-accept vs. invite-only, allowed peer domains, max foreign participants per room), and any rejected events with reasons (signature mismatch, unknown peer, policy violation).

What it doesn't do#

• No global account. Each user belongs to one home tenant. Federation is room-level visibility, not single-sign-on.
• No cross-tenant search. Search results are still scoped to your tenant; foreign messages are stored on your side too, so they're searchable from your end, but you can't search the foreign side's full corpus.
• No automatic call federation across hosts. Calls work cross-tenant via the local LiveKit server — both sides connect to your LiveKit, with a foreign-issued LiveKit token. If the foreign side runs their own LiveKit, calls need a separate setup.
• No bidirectional federation of E2E-encrypted rooms (rooms with incognito scope can't federate at all).

Federated DMs#

A federated DM is a 1:1 room with one local participant and one foreign participant. Created via POST /v1/me/federated-dms.

Where to go next#

• Tutorial: Join a federated room.
• Tutorial: Enable federation with a peer.
• API: Federation.