RTC-Beitrittstoken
Ein Teilnehmer benötigt kurzlebige Zugangsdaten, um einem Raum beizutreten. Ihr Backend kann diese auf zwei Arten abrufen:
| Vorgehensweise | Wie | Verwenden Sie diese Option, wenn |
|---|---|---|
| Vom Server generiert | Ihr Backend ruft POST /v1/rooms/{roomId}/tokens mit einem SchlüsselAPI | Standard. Ein AufrufAPI pro Beitritt. |
| Offline generiert | Ihr Backend signiert ein Beitrittstoken mit einem Projekt-Signaturschlüssel, ohne RTC aufzurufen; das Token wird ausgetauscht bei POST /v1/join | Hohe 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.
Vom Server generierte Anmeldeinformationen
Abschnitt betitelt „Vom Server generierte Anmeldeinformationen“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.
Projektsignaturschlüssel
Abschnitt betitelt „Projektsignaturschlüssel“Ein Signaturschlüssel gehört zu einem Projekt. Sein id ist das JWT kid.
| Algorithmus | Was RTC speichert | Was Sie aufbewahren |
|---|---|---|
HS256 (Standard) | Das gemeinsame Geheimnis, verschlüsselt | Das Geheimnis rtcsk_…, werden einmalig bei der Erstellung angezeigt |
ES256 | Der öffentliche Schlüssel P-256 | Der 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 Pfad | Ergebnis |
|---|---|
GET /v1/projects/{projectId}/signing-keys | Schlüssel: id, name, algorithm, prefix (HS256) oder publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt |
POST /v1/projects/{projectId}/signing-keys | 201, 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.
Format des Join-Tokens
Abschnitt betitelt „Format des Join-Tokens“Ein Join-Token ist ein JWT, das mit einem Projekt-Signaturschlüssel signiert wurde.
| Teil | Feld | Regeln |
|---|---|---|
| Header | alg | HS256 oder ES256, der Algorithmus des Schlüssels |
| Header | kid | Der Signaturschlüssel id |
| Ansprüche | aud | Stets rtc-join |
| Ansprüche | roomId | Der Raum im Projekt des Schlüssels |
| Ansprüche | iat, exp | Ausstellungs- und Ablaufzeiten in Sekunden; maximal eine Stunde Abstand |
| Ansprüche | jti | Eine eindeutige ID mit 8 bis 128 Zeichen (A-Z a-z 0-9 . _ : -); jedes Token kann verwendet werden einmal |
| Claims (optional) | sub oder identity | Ihre stabile Benutzer-ID (A-Z a-z 0-9 : _ -, bis zu 128); sind beide festgelegt, müssen sie übereinstimmen |
| Claims (optional) | name | Anzeigename, der anderen Teilnehmern angezeigt wird, maximal 80 Zeichen |
| Claims (optional) | role | host, cohost, participant, panelist oder attendee |
| Claims (optional) | permissions, canPublish | Was der Teilnehmer veröffentlichen darf, wie bei der REST-Token-Anfrage |
| Claims (optional) | metadata | Ihre eigene Zeichenfolge, bis zu 1 KB, für andere Teilnehmer sichtbar |
| Claims (optional) | ttlSeconds | Gültigkeitsdauer der vom Austausch zurückgegebenen Medienanmeldedaten: 30 bis 300 |
| Claims (optional) | transcribe | false: 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.
Node.js (jose)
Abschnitt betitelt „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)
Abschnitt betitelt „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"]})
Tauschen Sie ein Beitrittstoken aus
Abschnitt betitelt „Tauschen Sie ein Beitrittstoken aus“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.
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.