RTC join tokens
A participant needs short-lived credentials to join a room. Your backend can get them in two ways:
| Way | How | Use when |
|---|---|---|
| Server-minted | Your backend calls POST /v1/rooms/{roomId}/tokens with an API key | Default. One API call per join. |
| Offline-minted | Your backend signs a join token with a project signing key, without calling RTC; the token is exchanged at POST /v1/join | High 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.
Server-minted credentials
Section titled “Server-minted credentials”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.
Project signing keys
Section titled “Project signing keys”A signing key belongs to one project. Its id is the JWT kid.
| Algorithm | What RTC keeps | What you keep |
|---|---|---|
HS256 (default) | The shared secret, encrypted | The secret rtcsk_…, shown once at creation |
ES256 | The P-256 public key | The 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 path | Result |
|---|---|
GET /v1/projects/{projectId}/signing-keys | Keys: id, name, algorithm, prefix (HS256) or publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt |
POST /v1/projects/{projectId}/signing-keys | 201, 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.
Join token format
Section titled “Join token format”A join token is a JWT signed with a project signing key.
| Part | Field | Rules |
|---|---|---|
| Header | alg | HS256 or ES256, the key’s algorithm |
| Header | kid | The signing key id |
| Claims | aud | Always rtc-join |
| Claims | roomId | The room in the key’s project |
| Claims | iat, exp | Issued and expiry times in seconds; at most one hour apart |
| Claims | jti | A unique id, 8 to 128 characters (A-Z a-z 0-9 . _ : -); each token can be used once |
| Claims (optional) | sub or identity | Your stable user id (A-Z a-z 0-9 : _ -, up to 128); if both are set they must match |
| Claims (optional) | name | Display name shown to other participants, up to 80 characters |
| Claims (optional) | role | host, cohost, participant, panelist or attendee |
| Claims (optional) | permissions, canPublish | What the participant may publish, as in the REST token request |
| Claims (optional) | metadata | Your own string, up to 1 KB, visible to other participants |
| Claims (optional) | ttlSeconds | Lifetime of the media credentials returned by the exchange, 30 to 300 |
| Claims (optional) | transcribe | false: 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.
Node.js (jose)
Section titled “Node.js (jose)”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);}Python (PyJWT)
Section titled “Python (PyJWT)”import jsonimport osimport timeimport 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"]})Exchange a join token
Section titled “Exchange a join token”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.
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.