---
audience: everyone
summary: Cross-tenant rooms via a signed server-to-server protocol. Foreign participants
  are first-class members.
title: Federation
path: concepts/federation
status: published
---

# 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](/docs/scaiwave/tutorials/power-user/join-a-federated-room).
- Tutorial: [Enable federation with a peer](/docs/scaiwave/tutorials/developer/enable-federation-with-a-peer).
- API: [Federation](/docs/scaiwave/reference/api/federation).