Decide whether a session may start
const url = 'https://switchboard.mux.global/auth?jwt=example&jwt=<jwt>';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"id":"example","event":"connect","transport":"quic","path":"acme/room/42","query":"jwt=eyJhbGciOiJIUzI1NiIs...","tls":{"expires":1}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://switchboard.mux.global/auth?jwt=example&jwt=<jwt>' \ --header 'Content-Type: application/json' \ --data '{ "id": "example", "event": "connect", "transport": "quic", "path": "acme/room/42", "query": "jwt=eyJhbGciOiJIUzI1NiIs...", "tls": { "expires": 1 } }'The relay asks this for every session: once when a Client (or a peer
relay) connects, again every 30 seconds while it stays connected, and
once when it ends. It uses the [auth] url from enrollment.
Switchboard reads the Client’s credential from the query in the
request body, usually a Client token as jwt=, and answers with a
Grant: what the session may publish and subscribe to, and when it
lapses.
Every Grant a Self-hosted relay gets is limited to its Organization’s Namespaces, whatever the Client’s credential says.
Switchboard answers from the location nearest the relay, and keeps
answering while the rest of Switchboard is down. If the relay can’t
reach it at all, sessions already running continue until their
Grant’s expires, which is at most 5 minutes away. New sessions are
refused.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”The relay’s own Node key, not the Client’s token.
Request Bodyrequired
Section titled “Request Bodyrequired”Sent by the relay. Switchboard reads the fields below and ignores the rest.
object
The session’s ID.
Example
quicThe path the Client dialed.
Example
acme/room/42The Client’s raw query string. Its last jwt= is the credential.
Example
jwt=eyJhbGciOiJIUzI1NiIs...Present when the Client presented a certificate the relay verified.
object
Responses
Section titled “Responses”Admitted, with this Grant.
Moq-relay’s Grant. publish and subscribe are patterns relative to
the dialed path: ** is everything, live/** is live and everything
under it.
object
When the session ends if no revalidation succeeds before then. At most 5 minutes out, and never later than the Client token’s own expiry.
Seconds until the relay asks again. Currently 30.
The stats tier the relay counts this session’s traffic under. It
appears only when the session is another relay (peer is true)
and Switchboard is configured with a peer tier. When it’s absent,
the relay counts the session in the default tier, with Client
traffic.
The session is another relay, not a Client.
Example
{ "publish": [ "alice/**" ], "subscribe": [ "**" ], "revalidate": 30, "tier": "mesh"}Answer to an end event.
The request is malformed. The message says how.
object
Example generated
{ "error": "example"}The relay’s own credential is missing or unknown.
object
Example generated
{ "error": "example"}The session is refused. The message says why, and the relay writes it to its log. The Client sees a 401.
object
Examples
{ "error": "the token has expired"}{ "error": "the grant lies outside this relay's Namespaces, acme, acme-staging"}