---
audience: power_user
summary: Have a room with someone on another ScaiWave server. They appear as a real
  member.
title: Join a federated room
path: tutorials/power-user/join-a-federated-room
status: published
---

# Join a federated room

Federation lets you have a room with people on another ScaiWave
server — another tenant in the same instance, or a self-hosted
server entirely. Everyone in the room sees the same messages,
reactions, and presence.

## Prerequisites

The other server needs to:

- Be reachable on the internet (or your private network).
- Publish a valid `/.well-known/scaiwave/server` descriptor.
- Have your server's tenant on its accepted-peer list (or run an
  open peering policy).

Most ScaiLabs-hosted tenants federate openly with each other; for
private hosts your admin coordinates peering with theirs.

## Invite a federated participant

### Via the UI

In an existing room → **+ Invite** → toggle **Federated**. Type the
full FQID:

```text
@alice:acme.scaiwave.com
```

Click **Invite**. Your server signs the invite with its Ed25519 key
and POSTs it to `acme.scaiwave.com`. The foreign user gets the
invite in their notification panel; when they accept, they appear in
your member list as `@alice:acme.scaiwave.com`.

### Via the API

```bash
POST /v1/rooms/{room_id}/invitations
Content-Type: application/json

{ "fqid": "@alice:acme.scaiwave.com" }
```

### As a fresh DM

For 1:1 conversations across servers, use the federated-DM endpoint:

```bash
POST /v1/me/federated-dms
Content-Type: application/json

{ "fqid": "@alice:acme.scaiwave.com" }
```

Creates a DM room with you and the foreign user, federated to their
server.

## How it shows up

- **Member list**: foreign participants appear with their full FQID.
- **Chat header**: 🌐 badge indicating "federated room".
- **Messages**: indistinguishable from local — same bubbles, same
  reactions, same threading.
- **Presence**: their server publishes; you see online/idle/etc.
- **Calls**: work normally; the LiveKit token gets minted by your
  server but the foreign user joins it like any other call.

## What's different

- **Search**: foreign messages are stored locally and indexed —
  you'll find them in search. But you can't search the foreign
  side's full corpus from your end.
- **Notifications**: yours are governed by your settings; theirs by
  theirs.
- **Plugins**: each side's AI uses *its own server's* plugins. An
  AI on your side asking the AI on their side for a search is two
  separate plugin calls.

## What doesn't work

- **Incognito rooms** can't federate. The protocol refuses.
- **Bridge rooms** can't federate. They're already proxying for
  another platform.
- **Federation invites time out** after 7 days if the foreign user
  doesn't accept.
- **End-to-end encryption**: not yet. Messages are signed
  server-to-server, but the server can read them.

## Removing a federation link

A federated participant who leaves (or is kicked) is removed like
any other member. To stop *all* federation traffic with a peer:
admin → **Federation → Peers** → **Remove**. This severs every
shared room — anyone on either side is removed.

## When peering breaks

Federation is per-room and per-event. A peer being temporarily
unreachable doesn't lose messages — your server retries with
exponential backoff up to 24 hours. After that, the event is marked
failed in your audit log and won't be delivered.

If you suspect a peer is broken, admin → **Federation → Peers** →
the peer's row shows `last_seen` and `last_error` columns.

## Where to go next

- Tutorial: [Enable federation with a peer](/docs/scaiwave/tutorials/developer/enable-federation-with-a-peer) — admin setup.
- [Concepts: Federation](/docs/scaiwave/concepts/federation).
- API: [Federation](/docs/scaiwave/reference/api/federation).