Core concepts

The words below are used precisely everywhere in these docs. Each section links to where the concept is defined in full.

Who owns what

• Organization: A customer of Switchboard. It owns Namespaces, API keys and Self-hosted relays. People manage it as its Members, each signed in with their own Account. Owners can also delete Namespaces, invite people, remove Members, and change who is an Owner.
• Namespace: The first segment of every path you can sign for, owned by one Organization for good. If your Namespace is acme, everything you publish lives under acme/. The name is never reissued, even after it’s deleted. Use one per environment: acme for prod, acme-staging for staging.

See Organizations and Namespaces and Prod and staging.

Credentials

Credential	Held by	For
API key (sb_...)	Your backend	Managing your Organization through the Account API
Signing key (a JWK)	Your backend	Minting Client tokens without calling Switchboard
Client token (a JWT)	A publisher or viewer	Connecting to a relay
Relay enrollment token (sbe_...)	You, briefly	Enrolling a Self-hosted relay
Node key (sbn_...)	Your Self-hosted relay	Talking to Switchboard and its peers

Only a Client token should ever reach a browser or an app. A Signing key’s scope caps what it can sign, and relays enforce that cap on every token. See Credentials.

Paths and grants

A Client token has three claims that matter:

• root: the full path the token is anchored at, starting with your Namespace, like acme/room/42.
• put: prefixes under root it may publish to.
• get: prefixes under root it may subscribe to.

"" means everything under root. Prefixes match whole path segments, so live covers live/cam1 but not lively. A Client passes the token to the relay as ?jwt= on the URL it connects to. See Client tokens.

When you call the API, paths are relative to the Namespace (room/42). Inside a token they’re written out in full (acme/room/42). See Paths in the API and in tokens.

Tracks and objects

What a Client publishes and subscribes to, in the SDKs’ terms:

• Namespace (SDK): The ordered list of path fields a publisher connection serves, like ['run', '1']. It’s relative to the endpoint URL’s path. Not to be confused with the Switchboard Namespace, which is only the first segment of the full path.
• Track: A named sequence of objects within a namespace, like ticker or video.
• Object and group: An object is one payload of bytes the SDK doesn’t interpret. Objects are sent in groups. A plain write sends one object as its own group.
• Announce: A publisher announces its namespace so the relay can route subscriptions to it. A fresh namespace can briefly reject subscriptions (request error 16) while the announce propagates. Retry them.
• Demand: A publisher’s write waits until the relay wants the track, which means a subscriber exists.

The SDK vocabulary has every public name in both SDKs, and the behavior contract says exactly what each must do.

Endpoints

A Client connects to a relay endpoint. The SDKs’ DEFAULT_ENDPOINT is the hosted Relay, https://relay.mux.global. Put your token’s root in the endpoint’s path (https://relay.mux.global/acme/room/42) and name namespaces relative to it. The connection then can’t reach outside that root. roomEndpoint(['acme', 'room', '42']) (room_endpoint in Python) builds that URL. Pass an endpoint first to root another relay. A Client that spans several rooms under one grant can use the bare host instead, with namespaces that include the root. See room-rooted endpoints.

Relays

• Platform relay: A relay Mux runs. It may carry tracks from any Namespace. The Mux relays carry announcements between regions, so a publisher and a subscriber can each use their nearest relay.
• Self-hosted relay: A moq-relay you run and enroll in your Organization. It carries only your Organization’s Namespaces. See Running a Self-hosted relay.
• Admission: Switchboard deciding, for one relay, whether a session may start and with which grant. Relays ask through the Relay plane API.