Tokens de incorporación de RTC
Un participante necesita credenciales de corta duración para unirse a una sala. Su backend puede obtenerlas de dos maneras:
| Método | Cómo | Utilícelo cuando |
|---|---|---|
| Generado por el servidor | Su backend realiza una llamada POST /v1/rooms/{roomId}/tokens con una claveAPI | Por defecto. Una API llamada por cada incorporación. |
| Generado sin conexión | Su backend firma un token de incorporación con una clave de firma del proyecto, sin llamar a RTC; el token se intercambia en POST /v1/join | Volúmenes elevados de uniones, o cuando su backend no deba llamar a RTC en cada unión |
Ambas opciones proporcionan las mismas credenciales y aplican las mismas comprobaciones de estado, capacidad y plan de la sala. En ambos casos Su backend decide quién puede unirse a qué sala; nunca permita que un cliente elija su propia sala, función o permisos.
Credenciales generadas por el servidor
Sección titulada «Credenciales generadas por el servidor»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 clave necesita el tokens:write . La respuesta contiene token,
participantId, url, iceServers y expiresIn; consulte el
API referencia y el
flujo de incorporación.
Claves de firma del proyecto
Sección titulada «Claves de firma del proyecto»Una clave de firma pertenece a un proyecto. Su id es el JWT kid.
| Algoritmo | Lo que conserva RTC | Lo que debe conservar |
|---|---|---|
HS256 (por defecto) | El secreto compartido, cifrado | El secreto rtcsk_…, que se muestran una vez al crearlas |
ES256 | La clave pública P-256 | La clave privada: generada por RTC y mostrada una sola vez como JWK, o la suya propia (usted envía únicamente el JWK público) |
Cree claves en la consola de RTC o mediante su sesión de consola a través deAPI:
| Método y ruta | Resultado |
|---|---|
GET /v1/projects/{projectId}/signing-keys | Claves: id, name, algorithm, prefix (HS256) o publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt |
POST /v1/projects/{projectId}/signing-keys | 201, la clave y, una vez, su secret (HS256) o privateKeyJwk (ES256, generada) |
DELETE /v1/projects/{projectId}/signing-keys/{keyId} | { "revoked": true }; los tokens firmados con ella dejan de funcionar de inmediato |
El cuerpo de la creación es { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }.
expiresInDays acepta valores de 1 a 730; sin este valor, la clave no caduca. Un proyecto puede tener hasta cinco claves activas (SIGNING_KEY_LIMIT). Guarde la clave secreta o privada únicamente en el gestor de secretos de su servidor: nunca en un navegador, una aplicación móvil, un repositorio o un chat. El CHAMPREP AI asistente puede mostrar una lista de sus claves de firma, pero nunca crea una ni muestra una clave secreta.
Para rotar una clave, cree una nueva, impleméntela y, a continuación, revoque la antigua.
Formato del token de unión
Sección titulada «Formato del token de unión»Un token de unión es un JWT firmado con una clave de firma del proyecto.
| Parte | Campo | Normas |
|---|---|---|
| Encabezado | alg | HS256 o ES256, el algoritmo de la clave |
| Encabezado | kid | La clave de firma id |
| Reclamaciones | aud | Siempre rtc-join |
| Reclamaciones | roomId | La sala del proyecto de la clave |
| Reclamaciones | iat, exp | Tiempos de emisión y caducidad en segundos; con una diferencia máxima de una hora |
| Reclamaciones | jti | Un identificador único, de entre 8 y 128 caracteres (A-Z a-z 0-9 . _ : -); cada token puede utilizarse una vez |
| Reclamaciones (opcional) | sub o identity | Su identificador de usuario estable (A-Z a-z 0-9 : _ -, hasta 128); si se configuran ambos, deben coincidir |
| Reclamaciones (opcional) | name | Nombre que se muestra a los demás participantes, hasta 80 caracteres |
| Reclamaciones (opcional) | role | host, cohost, participant, panelist o attendee |
| Reclamaciones (opcional) | permissions, canPublish | Lo que el participante puede publicar, tal y como se indica en la solicitud de token REST |
| Reclamaciones (opcional) | metadata | Su propia cadena de texto, de hasta 1 KB, visible para los demás participantes |
| Reclamaciones (opcional) | ttlSeconds | Vida útil de las credenciales multimedia devueltas por el intercambio: de 30 a 300 |
| Reclamaciones (opcional) | transcribe | false: este participante nunca transcrito; sus pistas se graban, pero se omiten en la transcripción |
Mantenga breve la vida útil del token (unos pocos minutos son suficientes para una incorporación). Un token caducado, reutilizado o firmado incorrectamente da como respuesta 401
JOIN_GRANT_INVALID o 409
JOIN_GRANT_USED.
Node.js (jose)
Sección titulada «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)
Sección titulada «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"]})
Intercambiar un token de conexión
Sección titulada «Intercambiar un token de conexión»POST /v1/join con { "token": "<join token>" } devuelve el mismo cuerpo que
POST /v1/rooms/{roomId}/tokens. No necesita ninguna claveAPI: el token de conexión es la autorización.
curl --fail-with-body \ --request POST https://api.rtc.champrep.com/v1/join \ --header 'Content-Type: application/json' \ --data "{\"token\":\"$RTC_JOIN_TOKEN\"}"Intercambie el token de conexión desde su propio servidor o reenvíe el intercambio a través de él: el RTC solo aceptaAPI solicitudes del navegador procedentes de consolas CHAMPREPde , por lo que un
POST /v1/join Enviado por un navegador desde su dominio, se rechaza. Envíe las credenciales intercambiadas únicamente al usuario para el que se generó el token, a través de su propia conexión autenticada, y trate el token y las credenciales como información confidencial. Genere un nuevo token de conexión para cada conexión y reconexión.