01 — Getting started

Core concepts

Term Meaning
Room A call/meeting. Identified by a name you choose (e.g. order-4821, support-call-9). Rooms are isolated to your project.
Identity A unique string for each participant within a room (e.g. your user id). Reusing it reconnects the same user.
Token A short-lived JWT that authorizes one identity to join one room with specific permissions. Your backend mints it; your app uses it.
Grants What a token allows: publish, subscribe, send data, admin, etc. (a.k.a. "role").

Room names must match ^[A-Za-z0-9][A-Za-z0-9._-]{1,63}$ (letters, digits, ., _, -; 2–64 chars). They are isolated per project — your support never clashes with another customer's support.

Authentication (backend → API)

Every API call (except /ping) needs your API key + secret. Two equivalent ways:

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

or

X-Api-Key: YOUR_API_KEY
X-Api-Secret: YOUR_API_SECRET
  • Send Content-Type: application/json for requests with a body.
  • Never put these credentials in a mobile/web app. Only your backend uses them.

The token flow (the only flow you need)

  1. Your app (Flutter/web) asks your backend: "I want to join room X as user Y."
  2. Your backend calls POST /api/v1/tokens with your API key, room, and identity.
  3. arzbridge returns { token, ws_url, expires_in, ... }.
  4. Your backend returns token + ws_url to your app.
  5. Your app connects a LiveKit SDK to ws_url using token. Done.

You decide who can join what — the token is created on your terms (your auth, your rules), so arzbridge never needs to know about your users.

Response & error format

Success:

{ "data": { ... } }

Error:

{ "error": { "code": 422, "message": "The room field is required.", "fields": { "room": ["..."] } } }
HTTP Meaning
200 / 201 OK / created
401 Missing/invalid API credentials
403 Valid key, but missing a required scope, or quota reached
404 Room/participant/recording not found
422 Validation error (see error.fields)
429 Rate limit exceeded (see Retry-After header)
5xx Server/LiveKit issue — retry with backoff

Roles via grants

Choose grants when minting a token (full list in 02-api-reference.md):

Role Token options
Full participant (default) (none — publish + subscribe + data are on)
Viewer / webinar attendee { "can_publish": false }
Broadcaster only { "can_subscribe": false }
Moderator { "room_admin": true } (can mute/remove others via the API)
Hidden bot / recorder { "hidden": true }

Token lifetime (TTL)

A token only needs to live long enough to connect; the call continues after it expires. Default TTL is 6 hours; set ttl (seconds, 30–86400) to taste. Re-issue on demand from your backend.

Rate limits

Default 120 requests/minute per API key (token minting + management calls). A 429 includes Retry-After. Need more? Ask arzbridge to raise your limit.

Next: pick your backend — Node.js or Laravel — then wire up your Flutter app.