Pular para o conteúdo
Documentation

Tokens de entrada do RTC

Um participante precisa de credenciais de curta duração para ingressar em uma sala. Seu backend pode obtê-las de duas maneiras:

MétodoComoUtilize quando
Gerado pelo servidorSeu backend chama POST /v1/rooms/{roomId}/tokens com uma chaveAPIPadrão. Uma API chamada por entrada.
Gerado offlineSeu backend assina um token de entrada com uma chave de assinatura do projeto, sem chamar o RTC; o token é trocado em POST /v1/joinAltos volumes de adesão ou quando seu backend não deve chamar o RTC a cada adesão

Ambas fornecem as mesmas credenciais e aplicam as mesmas verificações de estado, capacidade e plano da sala. Em ambos os casos Seu backend decide quem pode ingressar em qual sala; nunca permita que um cliente escolha sua própria sala, função ou permissões.

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

A chave requer o tokens:write escopo. A resposta contém token, participantId, url, iceServers e expiresIn; consulte o API referência e o fluxo de adesão.

Uma chave de assinatura pertence a um projeto. Sua id é o JWT kid.

AlgoritmoO que a RTC mantémO que você mantém
HS256 (padrão)O segredo compartilhado, criptografadoO segredo rtcsk_…, exibidas uma vez na criação
ES256A chave pública P-256A chave privada: gerada pelo RTC e exibida uma única vez como um JWK, ou a sua própria (você envia apenas o JWK público)

Crie chaves no console do RTC ou por meio de sua sessão no console utilizando o API:

Método e caminhoResultado
GET /v1/projects/{projectId}/signing-keysChaves: id, name, algorithm, prefix (HS256) ou publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt
POST /v1/projects/{projectId}/signing-keys201, a chave e, uma vez, sua secret (HS256) ou privateKeyJwk (ES256, gerada)
DELETE /v1/projects/{projectId}/signing-keys/{keyId}{ "revoked": true }; os tokens assinados com ela deixam de funcionar imediatamente

O corpo da criação é { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }. expiresInDays aceita valores de 1 a 730; sem ele, a chave não expira. Um projeto pode ter até cinco chaves ativas (SIGNING_KEY_LIMIT). Mantenha a chave secreta ou privada exclusivamente no gerenciador de segredos do seu servidor: nunca em um navegador, um aplicativo móvel , um repositório ou um chat. O CHAMPREP AI assistente pode listar suas chaves de assinatura , mas nunca cria uma nem exibe um segredo.

Para fazer a rotação, crie uma nova chave, implemente-a e, em seguida, revogue a antiga.

Um token de adesão é um JWT assinado com uma chave de assinatura do projeto.

ParteCampoRegras
CabeçalhoalgHS256 ou ES256, o algoritmo da chave
CabeçalhokidA chave de assinatura id
ReivindicaçõesaudSempre rtc-join
ReivindicaçõesroomIdA sala no projeto da chave
Reivindicaçõesiat, expTempos de emissão e validade em segundos; com intervalo máximo de uma hora
ReivindicaçõesjtiUm ID exclusivo, de 8 a 128 caracteres (A-Z a-z 0-9 . _ : -); cada token pode ser utilizado uma vez
Reivindicações (opcional)sub ou identitySeu ID de usuário estável (A-Z a-z 0-9 : _ -, até 128); se ambos estiverem definidos, devem coincidir
Reivindicações (opcional)nameNome de exibição mostrado a outros participantes, com até 80 caracteres
Reivindicações (opcional)rolehost, cohost, participant, panelist ou attendee
Reivindicações (opcional)permissions, canPublishO que o participante pode publicar, conforme a solicitação de token REST
Reivindicações (opcional)metadataSua própria sequência de caracteres, de até 1 KB, visível para outros participantes
Reivindicações (opcional)ttlSecondsVigência das credenciais de mídia retornadas pela troca: de 30 a 300
Reivindicações (opcional)transcribefalse: este participante nunca é transcrito; suas faixas são gravadas, mas ignoradas na transcrição

Mantenha o tempo de vida do token curto (alguns minutos são suficientes para uma conexão). Um token expirado, reutilizado ou assinado incorretamente resulta em 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 com { "token": "<join token>" } retorna o mesmo corpo que POST /v1/rooms/{roomId}/tokens. Não é necessária nenhuma API chave: o token de conexão é a autorização.

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

Troque o token de conexão a partir de seu próprio servidor ou retransmita a troca por meio dele: o RTC aceitaAPI solicitações CHAMPREPde navegador apenas de consoles, portanto, um POST /v1/join enviada por um navegador a partir do seu domínio é recusada. Envie as credenciais trocadas apenas ao usuário para o qual o token foi gerado, por meio de sua própria conexão autenticada, e trate o token e as credenciais como informações confidenciais. Gere um novo token de participação para cada entrada e reconexão.