Zum Inhalt springen
Documentation

RTC-Beitrittstoken

Ein Teilnehmer benötigt kurzlebige Zugangsdaten, um einem Raum beizutreten. Ihr Backend kann diese auf zwei Arten abrufen:

VorgehensweiseWieVerwenden Sie diese Option, wenn
Vom Server generiertIhr Backend ruft POST /v1/rooms/{roomId}/tokens mit einem SchlüsselAPIStandard. Ein AufrufAPI pro Beitritt.
Offline generiertIhr Backend signiert ein Beitrittstoken mit einem Projekt-Signaturschlüssel, ohne RTC aufzurufen; das Token wird ausgetauscht bei POST /v1/joinHohe Beitrittsvolumina oder wenn Ihr Backend nicht bei jedem Beitritt RTC aufrufen soll

Beide Verfahren liefern dieselben Anmeldedaten und wenden dieselben Prüfungen hinsichtlich Raumstatus, Kapazität und Tarif an. In beiden Fällen Ihr Backend entscheidet, wer welchem Raum beitreten darf; lassen Sie niemals zu, dass ein Client seinen eigenen Raum, seine Rolle oder seine Berechtigungen selbst wählt.

Terminal-Fenster
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}'

Der Schlüssel benötigt den tokens:write Gültigkeitsbereich. Die Antwort enthält token, participantId, url, iceServers und expiresIn; siehe die API Referenz und der Join-Ablauf.

Ein Signaturschlüssel gehört zu einem Projekt. Sein id ist das JWT kid.

AlgorithmusWas RTC speichertWas Sie aufbewahren
HS256 (Standard)Das gemeinsame Geheimnis, verschlüsseltDas Geheimnis rtcsk_…, werden einmalig bei der Erstellung angezeigt
ES256Der öffentliche Schlüssel P-256Der private Schlüssel: von RTC generiert und einmalig als JWK angezeigt, oder Ihr eigener (Sie senden nur den öffentlichen JWK)

Erstellen Sie Schlüssel in der RTC-Konsole oder über Ihre Konsolensitzung mithilfe des BefehlsAPI:

Methode und PfadErgebnis
GET /v1/projects/{projectId}/signing-keysSchlüssel: id, name, algorithm, prefix (HS256) oder publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt
POST /v1/projects/{projectId}/signing-keys201, der Schlüssel und einmalig dessen secret (HS256) oder privateKeyJwk (ES256, generiert)
DELETE /v1/projects/{projectId}/signing-keys/{keyId}{ "revoked": true }; damit signierte Token verlieren sofort ihre Gültigkeit

Der Erstellungstext lautet { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }. expiresInDays akzeptiert Werte von 1 bis 730; ohne diesen Wert läuft der Schlüssel nicht ab. Ein Projekt kann bis zu fünf aktive Schlüssel haben (SIGNING_KEY_LIMIT). Bewahren Sie den geheimen oder privaten Schlüssel ausschließlich im Secret Manager Ihres Servers auf: niemals in einem Browser, einer mobilen App, einem Repository oder einem Chat. Der CHAMPREP AI Assistent kann Ihre Signaturschlüssel auflisten, erstellt jedoch niemals einen neuen und zeigt auch kein Geheimnis an.

Um eine Schlüsselrotation durchzuführen, erstellen Sie einen neuen Schlüssel, stellen Sie ihn bereit und widerrufen Sie anschließend den alten.

Ein Join-Token ist ein JWT, das mit einem Projekt-Signaturschlüssel signiert wurde.

TeilFeldRegeln
HeaderalgHS256 oder ES256, der Algorithmus des Schlüssels
HeaderkidDer Signaturschlüssel id
AnsprücheaudStets rtc-join
AnsprücheroomIdDer Raum im Projekt des Schlüssels
Ansprücheiat, expAusstellungs- und Ablaufzeiten in Sekunden; maximal eine Stunde Abstand
AnsprüchejtiEine eindeutige ID mit 8 bis 128 Zeichen (A-Z a-z 0-9 . _ : -); jedes Token kann verwendet werden einmal
Claims (optional)sub oder identityIhre stabile Benutzer-ID (A-Z a-z 0-9 : _ -, bis zu 128); sind beide festgelegt, müssen sie übereinstimmen
Claims (optional)nameAnzeigename, der anderen Teilnehmern angezeigt wird, maximal 80 Zeichen
Claims (optional)rolehost, cohost, participant, panelist oder attendee
Claims (optional)permissions, canPublishWas der Teilnehmer veröffentlichen darf, wie bei der REST-Token-Anfrage
Claims (optional)metadataIhre eigene Zeichenfolge, bis zu 1 KB, für andere Teilnehmer sichtbar
Claims (optional)ttlSecondsGültigkeitsdauer der vom Austausch zurückgegebenen Medienanmeldedaten: 30 bis 300
Claims (optional)transcribefalse: Dieser Teilnehmer ist niemals transkribiert; deren Titel werden aufgezeichnet, bei der Transkription jedoch übersprungen

Halten Sie die Lebensdauer des Tokens kurz (einige Minuten reichen für einen Beitritt aus). Ein abgelaufenes, wiederverwendetes oder falsch signiertes Token führt zu 401 JOIN_GRANT_INVALID oder 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 mit { "token": "<join token>" } gibt denselben Body zurück wie POST /v1/rooms/{roomId}/tokens. Es ist kein SchlüsselAPI erforderlich: Das Beitrittstoken dient als Autorisierung.

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

Tauschen Sie das Join-Token über Ihren eigenen Server aus oder leiten Sie den Austausch über diesen weiter: RTC akzeptiertAPI Browseranfragen nur vonCHAMPREP Konsolen, daher ist ein POST /v1/join Die von einem Browser Ihrer Domain gesendete Anfrage wird abgelehnt. Senden Sie die ausgetauschten Anmeldedaten ausschließlich an den Benutzer, für den das Token generiert wurde, über Ihre eigene authentifizierte Verbindung, und behandeln Sie das Token und die Anmeldedaten vertraulich. Generieren Sie für jeden Beitritt und jede erneute Verbindung ein neues Beitrittstoken.