Media API v1 › Authentication

Authentication concept

An auth token is a JWT your backend generates — signed with your API key + secret — and passed to VideoSDK.join() as the token field of JoinOptions. It is never generated on the client: minting requires the app secret, which must stay on your server.

v1 uses a grant-based model. The token carries a grant object — a set of capability flags — that the SFU enforces server-side. The SDK doesn't gate anything locally; the token is the source of truth.

Token claims

The JWT payload. roomId and grant are the load-bearing claims; the rest are standard JWT registered claims plus two VideoSDK-specific identity/tier markers.

roomId scoping — optional, with guardrails

roomId is optional. Present → the token is scoped to that one room (joining a different roomId rejects with UNAUTHORIZED_ROOM). Omitted → domain-wide (any room in the project). Two guardrails bound the risk of domain-wide tokens.

The guardrails

Why this shape

• Room-scoped is the secure default — least privilege; a leak hits one meeting. Required by LiveKit and 100ms for exactly this reason.
• Domain-wide is a real convenience — one token for a multi-room viewer / lobby experience, or a trusted server token; mint before the room is known. Daily (omit room_name) and Agora (wildcard "*") both support it.
• The guardrails close the blast-radius hole that makes the strict SDKs refuse it: short-lived + unprivileged means a domain-wide token is bounded in both time and power.

The grant

The capability object. Each flag is enforced server-side by the SFU. A grant with everything false is a no-op participant (connected, but can't publish, subscribe, or moderate). Mint the narrowest grant that fits the role.

Sample token

A host token — on-stage, full media, data, all services, and moderation.

{
  "roomId": "team-standup",
  "participantId": "alice-42",
  "isViewer": false,
  "joinPolicy": { "mode": "direct" },

  "grant": {
    "canPublish": true,
    "canPublishSources": ["camera", "microphone", "screen"],
    "canSubscribe": true,
    "canPublishData": true,
    "canSubscribeData": true,
    "canRecord": true,
    "canHls": true,
    "canLivestream": true,
    "canTranscribe": true,
    "canWhiteboard": true,
    "canModerate": true
  },

  "iss": "vsdk_live_a1b2c3d4",
  "iat": 1716800000,
  "nbf": 1716800000,
  "exp": 1716803600,
  "jti": "e8c1f0a2-7b3d-4e6f-9a01-2c3d4e5f6071"
}

Tier & participant events

isViewer decides whether a participant is on-stage (speaker) or audience (viewer). The two tiers reach the client through different surfaces:

Net effect: a 10-person stage with a 10,000-person audience produces 10 participant events, not 10,010 — the 10,000 viewers are reflected only in the coalesced participant-count-changed event ({ speaker, viewer, total }) and become enumerable on demand via getParticipants.

Errors

All auth failures surface on VideoSDK.join() as a rejected Promise with kind === ErrorKind.Auth. Catch the whole class with err.kind === ErrorKind.Auth and branch on err.code if you need specifics. Full inventory: Errors → VideoSDK.join().

Open questions

Two token-related design questions still being decided. The shapes below are the options on the table; none are locked. Until they are, mint an exp comfortably longer than your expected session length, and rely on token re-mint + rejoin for grant changes.

Q1 — What happens when the token expires mid-call?

Tokens have an exp claim; long meetings outlive a single mint. The SDK needs a way to obtain a fresh token without disconnecting the user.

Current lean: provider callback + keep token: string for the simple short-call path. Sub-questions to settle if we go that way: how far before exp to pre-refresh (default 30–60s), the retry / backoff policy on provider failure, and the disconnect reason if refresh ultimately fails (likely DisconnectReason.TokenExpired).

Q2 — How does a participant's grant change mid-call?

Today the grant is set at token-mint time and frozen for the session. Real cases need to change it: host promotes a viewer to speaker, demotes a speaker, revokes recording mid-meeting, flips isViewer. How does the new grant reach the running client?

Current lean: hybrid — refresh-driven for v1 (one mechanism for both expiry and permission changes), updateParticipant deferred. Sub-questions: should the client emit a grant-changed event when its own grant updates (so the app can re-render UI / disable buttons)? Should an isViewer flip mid-call retro-fire participant-joined / participant-left as the participant moves between on-stage and audience tiers?

Example

The two halves of the flow: your backend mints a scoped token with a grant; the client passes it to join().

// === YOUR BACKEND — never ship the secret to the client ===
import jwt from 'jsonwebtoken';

function mintToken({ roomId, participantId, role }) {
  const grant =
    role === 'host'
      ? {
          canPublish: true,
          canPublishSources: ['camera', 'microphone', 'screen'],
          canSubscribe: true,
          canPublishData: true,
          canRecord: true, canHls: true, canLivestream: true, canTranscribe: true,
          canModerate: true,
        }
      : {
          canPublish: true,
          canPublishSources: ['camera', 'microphone'],
          canSubscribe: true,
          canPublishData: true,
          canRecord: false, canHls: false, canLivestream: false, canTranscribe: false,
          canModerate: false,
        };

  return jwt.sign(
    {
      roomId,
      participantId,
      isViewer: false,        // on-stage
      grant,
    },
    process.env.VIDEOSDK_APP_SECRET,   // signing key — backend only
    {
      algorithm: 'HS256',
      issuer: process.env.VIDEOSDK_API_KEY,   // iss
      expiresIn: '1h',                        // exp
    },
  );
}

// Expose behind your own auth — e.g. POST /api/meeting-token
app.post('/api/meeting-token', requireLogin, (req, res) => {
  const token = mintToken({
    roomId: req.body.roomId,
    participantId: req.user.id,
    role: req.user.role,
  });
  res.json({ token });
});

// === CLIENT — never mints a token; just fetches and joins ===
import { VideoSDK, ErrorKind } from '@videosdk/js';

const { token } = await fetch('/api/meeting-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ roomId: 'team-standup' }),
}).then((r) => r.json());

try {
  const room = await VideoSDK.join({ token, roomId: 'team-standup', name: 'Alice' });
  console.log('connected', room.localParticipant.id);
} catch (err) {
  if (err.kind === ErrorKind.Auth) showLoginUI();   // any auth failure
  else                             showGenericError(err);
}

See also: Waiting Lobby VideoSDK.join() JoinOptions Room → Events Errors → VideoSDK.join()