Using a video room access token

When you create a room, join a room, or a guest redeems an invite, Orbit returns an access token — a short-lived JWT scoped to one room and one identity. This is the single most common point of confusion: you have the token in your hand, and it isn’t obvious what to do with it. The short answer: an access token is an SDK credential. You pass it to the @orbit/media-client SDK’s Room.connect() call to put a participant into the live room. It is not an HTTP Authorization header, and it is not a link you send to a non-technical guest.

If you just want to get a person into a room and you are not building on the SDK, you probably want a guest invite link, not a raw token. Use the Share button on a room, or POST /video/rooms-scheduled/{id}/invites, to mint a link a guest can open in their browser. Reach for an access token only when your own client code connects to the room.

Where the token comes from

Three endpoints return an access token. They differ in who the token is for, but the token itself is used the same way in every case.

You called	Field in the response	Token is for
`POST /video/rooms-scheduled` (create)	`host_token`	the creator, joining as host
`POST /video/rooms-scheduled/{id}/join`	`token`	a named participant you mint for
`POST /video/invites/{inviteToken}/redeem`	`token`	a guest redeeming a shared link

Each response also carries the media-server WebSocket URL you connect to. Prefer livekit_url; fall back to the legacy ws_url alias if it is absent.

Step 1 — Get a token

Mint a per-participant token for an existing room. identity must be unique per person in the room; participant_tier sets what they can do (viewer, panelist, host, hidden_supervisor).

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{roomId}/join" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "guest-jane",
    "display_name": "Jane Doe",
    "participant_tier": "panelist"
  }'

The response gives you the two values you need in the next step — token and livekit_url:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "livekit_url": "wss://media.orbit.devotel.io",
    "ws_url": "wss://media.orbit.devotel.io",
    "participant_tier": "panelist",
    "permissions": { "can_publish": true, "can_subscribe": true },
    "expires_at": "2026-05-10T15:05:00Z",
    "expires_in_seconds": 3600
  }
}

Step 2 — Connect the participant with the token

Pass the token and the URL to Room.connect(). This is the “where do I use it” answer: the token is the second argument to connect().

import { Room } from "@orbit/media-client";

const room = new Room();

// `wsUrl` is `livekit_url` from the response (fall back to `ws_url`).
// `token` is the JWT from the response — never a header, never a link.
await room.connect(wsUrl, token);

room.on("participantConnected", (participant) => {
  console.log(`${participant.identity} joined`);
});

// Publish camera + mic if the token's grant allows it.
await room.localParticipant.enableCameraAndMicrophone();

The upstream livekit-client SDK still works at the protocol level, but @orbit/media-client is the supported client. If you use livekit-client, point it at the livekit_url from the response — never at livekit.cloud, which was retired.

Respect the effective grant

participant_tier and permissions in the response are the effective grant after any host-to-participant downgrade and any waiting-room clamp — not necessarily what you requested. Check permissions.can_publish before you show a publish (camera/mic) control. When lobby_downgraded is true, an armed waiting room forced this join to receive-only viewer; show a “waiting for the host to admit you” state instead of a publish button.

Tokens expire — re-mint before they do

An access token is valid for a limited window (expires_in_seconds from issue, and an absolute expires_at). Re-mint a fresh token and reconnect before expires_at to avoid dropping mid-session. Requesting a new token for the same identity is safe.

Handle it like a credential

Anyone holding a valid token joins the room as the named identity, so treat it like a password:

Deliver it to your client over a secure channel (your own authenticated API), not by pasting it into chat or email.
Do not log it or embed it in a shareable URL.
To invite a human who is not running your integration, send a guest invite link instead of a token — see below.

Inviting a guest instead

If the person joining is not your own SDK client — a customer, a vendor, anyone without your integration — mint a guest invite link rather than a raw token. The link redeems to a token on the server for you, so the guest never touches a JWT:

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled/{roomId}/invites" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "expires_in_seconds": 86400, "max_uses": 1 }'

Embed the returned invite_token in a URL and send that. In the dashboard, the Share button on a room does exactly this.

Reference

For the full request and response schema of every endpoint mentioned here — create, join, invite, redeem, and the complete field list — see the Video API reference.

WhatsApp

Guides

Using a video room access token

Using a video room access token

Where the token comes from

Step 1 — Get a token

Step 2 — Connect the participant with the token

Respect the effective grant

Tokens expire — re-mint before they do

Handle it like a credential

Inviting a guest instead

Reference

​Using a video room access token

​Where the token comes from

​Step 1 — Get a token

​Step 2 — Connect the participant with the token

​Respect the effective grant

​Tokens expire — re-mint before they do

​Handle it like a credential

​Inviting a guest instead

​Reference

Using a video room access token

Where the token comes from

Step 1 — Get a token

Step 2 — Connect the participant with the token

Respect the effective grant

Tokens expire — re-mint before they do

Handle it like a credential

Inviting a guest instead

Reference