Aller au contenu
Documentation

Jetons de connexion RTC

Un participant a besoin d’identifiants à durée de vie limitée pour rejoindre une salle. Votre backend peut les obtenir de deux manières :

MéthodeCommentÀ utiliser lorsque
Généré par le serveurVotre backend appelle POST /v1/rooms/{roomId}/tokens avec une cléAPIPar défaut. Un API appel par connexion.
Génération hors ligneVotre backend signe un jeton de connexion à l’aide d’une clé de signature du projet, sans appeler RTC ; le jeton est échangé lors de POST /v1/joinVolumes de rejoints élevés, ou lorsque votre backend ne doit pas appeler RTC à chaque rejoint

Les deux méthodes fournissent les mêmes identifiants et appliquent les mêmes vérifications concernant l’état de la salle, sa capacité et son forfait. Dans les deux cas C’est votre backend qui décide qui peut rejoindre quelle salle; ne laissez jamais un client choisir lui-même sa salle, son rôle ou ses autorisations.

Fenêtre de terminal
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}'

La clé nécessite le tokens:write portée. La réponse contient token, participantId, url, iceServers et expiresIn; voir le API référence et le flux de jonction.

Une clé de signature appartient à un seul projet. Son id est le JWT kid.

AlgorithmeCe que RTC conserveCe que vous conservez
HS256 (par défaut)Le secret partagé, chiffréLe secret rtcsk_…, affichées une seule fois lors de la création
ES256La clé publique P-256La clé privée : générée par RTC et affichée une seule fois sous forme de JWK, ou la vôtre (vous n’envoyez que le JWK public)

Créez des clés dans la console RTC, ou via votre session de console à l’aide de la commande API:

Méthode et chemin d’accèsRésultat
GET /v1/projects/{projectId}/signing-keysClés : id, name, algorithm, prefix (HS256) ou publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt
POST /v1/projects/{projectId}/signing-keys201, la clé et, une seule fois, son secret (HS256) ou privateKeyJwk (ES256, générée)
DELETE /v1/projects/{projectId}/signing-keys/{keyId}{ "revoked": true }; les jetons signés avec celle-ci cessent immédiatement de fonctionner

Le corps de la création est { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }. expiresInDays accepte une valeur comprise entre 1 et 730 ; en l’absence de cette valeur, la clé n’expire pas. Un projet peut disposer de cinq clés actives au maximum (SIGNING_KEY_LIMIT). Conservez la clé secrète ou privée exclusivement dans le gestionnaire de secrets de votre serveur : jamais dans un navigateur, une application mobile, un référentiel ou une discussion. L’assistantCHAMPREP AI peut répertorier vos clés de signature , mais ne crée jamais de clé ni n’affiche de secret.

Pour effectuer une rotation, créez une nouvelle clé, déployez-la, puis révoquez l’ancienne.

Un jeton de jonction est un JWT signé avec une clé de signature de projet.

PartieChampRègles
En-têtealgHS256 ou ES256, l’algorithme de la clé
En-têtekidLa clé de signature id
RéclamationsaudToujours rtc-join
RéclamationsroomIdLa salle dans le projet de la clé
Réclamationsiat, expHeures d’émission et d’expiration en secondes ; écart maximal d’une heure
RéclamationsjtiUn identifiant unique, de 8 à 128 caractères (A-Z a-z 0-9 . _ : -) ; chaque jeton peut être utilisé une fois
Réclamations (facultatif)sub ou identityVotre identifiant utilisateur stable (A-Z a-z 0-9 : _ -, jusqu’à 128) ; si les deux sont définis, ils doivent correspondre
Réclamations (facultatif)nameNom d’affichage visible par les autres participants, 80 caractères maximum
Réclamations (facultatif)rolehost, cohost, participant, panelist ou attendee
Réclamations (facultatif)permissions, canPublishCe que le participant est autorisé à publier, comme dans la requête de jeton REST
Réclamations (facultatif)metadataVotre propre chaîne de caractères, d’une taille maximale de 1 Ko, visible par les autres participants
Réclamations (facultatif)ttlSecondsDurée de vie des identifiants multimédia renvoyés par l’échange : de 30 à 300
Réclamations (facultatif)transcribefalse: ce participant n’est jamais transcrit; leurs pistes sont enregistrées mais ignorées lors de la transcription

Veillez à ce que la durée de vie du jeton soit courte (quelques minutes suffisent pour une connexion). Un jeton expiré, réutilisé ou mal signé renvoie 401 JOIN_GRANT_INVALID ou 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 avec { "token": "<join token>" } renvoie le même corps que POST /v1/rooms/{roomId}/tokens. Aucune cléAPI n’est nécessaire : le jeton de connexion constitue l’ autorisation.

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

Échangez le jeton de connexion depuis votre propre serveur, ou faites transiter l’échange par celui-ci : le RTC n’accepteAPI les requêtes de navigateur provenant que des consoles CHAMPREPde , donc un POST /v1/join envoyée par un navigateur depuis votre domaine est refusée. Envoyez les informations d’identification échangées uniquement à l’utilisateur pour lequel le jeton a été généré, via votre propre connexion authentifiée, et traitez le jeton et les informations d’identification comme des informations confidentielles. Générez un nouveau jeton de connexion à chaque connexion et reconnexion.