Skip to content
Documentation

RTC join tokens

A participant needs short-lived credentials to join a room. Your backend can get them in two ways:

WayHowUse when
Server-mintedYour backend calls POST /v1/rooms/{roomId}/tokens with an API keyDefault. One API call per join.
Offline-mintedYour backend signs a join token with a project signing key, without calling RTC; the token is exchanged at POST /v1/joinHigh join volumes, or when your backend should not call RTC on every join

Both give the same credentials and apply the same room state, capacity and plan checks. In both cases your backend decides who may join which room; never let a client choose its own room, role or permissions.

Terminal window
curl --fail-with-body \
--request POST "https://api.rtc.champrep.com/v1/rooms/$RTC_ROOM_ID/tokens" \
--header "Authorization: Bearer $RTC_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"canPublish":true}'

The key needs the tokens:write scope. The response holds token, participantId, url, iceServers and expiresIn; see the API reference and the join flow.

A signing key belongs to one project. Its id is the JWT kid.

AlgorithmWhat RTC keepsWhat you keep
HS256 (default)The shared secret, encryptedThe secret rtcsk_…, shown once at creation
ES256The P-256 public keyThe private key: generated by RTC and shown once as a JWK, or your own (you send only the public JWK)

Create keys in the RTC console, or with your console session through the API:

Method and pathResult
GET /v1/projects/{projectId}/signing-keysKeys: id, name, algorithm, prefix (HS256) or publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt
POST /v1/projects/{projectId}/signing-keys201, the key and, once, its secret (HS256) or privateKeyJwk (ES256, generated)
DELETE /v1/projects/{projectId}/signing-keys/{keyId}{ "revoked": true }; tokens signed with it stop working at once

The create body is { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }. expiresInDays accepts 1 to 730; without it the key does not expire. A project can have up to five active keys (SIGNING_KEY_LIMIT). Keep the secret or private key in your server’s secret manager only: never in a browser, a mobile app, a repository or a chat. The CHAMPREP AI assistant can list your signing keys but never creates one or shows a secret.

To rotate, create a new key, deploy it, then revoke the old one.

A join token is a JWT signed with a project signing key.

PartFieldRules
HeaderalgHS256 or ES256, the key’s algorithm
HeaderkidThe signing key id
ClaimsaudAlways rtc-join
ClaimsroomIdThe room in the key’s project
Claimsiat, expIssued and expiry times in seconds; at most one hour apart
ClaimsjtiA unique id, 8 to 128 characters (A-Z a-z 0-9 . _ : -); each token can be used once
Claims (optional)sub or identityYour stable user id (A-Z a-z 0-9 : _ -, up to 128); if both are set they must match
Claims (optional)nameDisplay name shown to other participants, up to 80 characters
Claims (optional)rolehost, cohost, participant, panelist or attendee
Claims (optional)permissions, canPublishWhat the participant may publish, as in the REST token request
Claims (optional)metadataYour own string, up to 1 KB, visible to other participants
Claims (optional)ttlSecondsLifetime of the media credentials returned by the exchange, 30 to 300
Claims (optional)transcribefalse: this participant is never transcribed; their tracks are recorded but skipped by transcription

Keep the token lifetime short (a few minutes is enough for a join). An expired, reused or wrongly signed token answers 401 JOIN_GRANT_INVALID or 409 JOIN_GRANT_USED.

import { randomUUID } from 'node:crypto';
import { SignJWT, importJWK } from 'jose';
// HS256: the key is the UTF-8 bytes of the whole rtcsk_ secret.
const alg = 'HS256';
const key = new TextEncoder().encode(process.env.RTC_SIGNING_SECRET);
// ES256 instead:
// const alg = 'ES256';
// const key = await importJWK(JSON.parse(process.env.RTC_SIGNING_PRIVATE_JWK), 'ES256');
export async function mintJoinToken({ roomId, userId, displayName }) {
return new SignJWT({ roomId, name: displayName, role: 'participant', canPublish: true })
.setProtectedHeader({ alg, kid: process.env.RTC_SIGNING_KEY_ID })
.setAudience('rtc-join')
.setSubject(userId)
.setIssuedAt()
.setExpirationTime('5m')
.setJti(randomUUID())
.sign(key);
}
import json
import os
import time
import uuid
import jwt # pip install "pyjwt[crypto]"
# HS256: the key is the whole rtcsk_ secret.
KEY = os.environ["RTC_SIGNING_SECRET"]
ALGORITHM = "HS256"
# ES256 instead:
# KEY = jwt.PyJWK(json.loads(os.environ["RTC_SIGNING_PRIVATE_JWK"])).key
# ALGORITHM = "ES256"
def mint_join_token(room_id: str, user_id: str, display_name: str) -> str:
now = int(time.time())
claims = {
"aud": "rtc-join",
"roomId": room_id,
"sub": user_id,
"name": display_name,
"role": "participant",
"canPublish": True,
"iat": now,
"exp": now + 300,
"jti": str(uuid.uuid4()),
}
return jwt.encode(claims, KEY, algorithm=ALGORITHM, headers={"kid": os.environ["RTC_SIGNING_KEY_ID"]})

POST /v1/join with { "token": "<join token>" } returns the same body as POST /v1/rooms/{roomId}/tokens. It needs no API key: the join token is the authorization.

Terminal window
curl --fail-with-body \
--request POST https://api.rtc.champrep.com/v1/join \
--header 'Content-Type: application/json' \
--data "{\"token\":\"$RTC_JOIN_TOKEN\"}"

Exchange the join token from your own server, or relay the exchange through it: the RTC API accepts browser requests only from CHAMPREP’s consoles, so a POST /v1/join sent by a browser from your domain is refused. Send the exchanged credentials only to the user the token was minted for, over your own authenticated connection, and treat the token and the credentials as secrets. Mint a new join token for every join and reconnection.