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étodo | Como | Utilize quando |
|---|---|---|
| Gerado pelo servidor | Seu backend chama POST /v1/rooms/{roomId}/tokens com uma chaveAPI | Padrão. Uma API chamada por entrada. |
| Gerado offline | Seu backend assina um token de entrada com uma chave de assinatura do projeto, sem chamar o RTC; o token é trocado em POST /v1/join | Altos 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.
Credenciais geradas pelo servidor
Seção intitulada “Credenciais geradas pelo 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}'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.
Chaves de assinatura do projeto
Seção intitulada “Chaves de assinatura do projeto”Uma chave de assinatura pertence a um projeto. Sua id é o JWT kid.
| Algoritmo | O que a RTC mantém | O que você mantém |
|---|---|---|
HS256 (padrão) | O segredo compartilhado, criptografado | O segredo rtcsk_…, exibidas uma vez na criação |
ES256 | A chave pública P-256 | A 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 caminho | Resultado |
|---|---|
GET /v1/projects/{projectId}/signing-keys | Chaves: id, name, algorithm, prefix (HS256) ou publicKeyJwk (ES256), createdAt, expiresAt, revokedAt, lastUsedAt |
POST /v1/projects/{projectId}/signing-keys | 201, 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.
Formato do token de adesão
Seção intitulada “Formato do token de adesão”Um token de adesão é um JWT assinado com uma chave de assinatura do projeto.
| Parte | Campo | Regras |
|---|---|---|
| Cabeçalho | alg | HS256 ou ES256, o algoritmo da chave |
| Cabeçalho | kid | A chave de assinatura id |
| Reivindicações | aud | Sempre rtc-join |
| Reivindicações | roomId | A sala no projeto da chave |
| Reivindicações | iat, exp | Tempos de emissão e validade em segundos; com intervalo máximo de uma hora |
| Reivindicações | jti | Um 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 identity | Seu ID de usuário estável (A-Z a-z 0-9 : _ -, até 128); se ambos estiverem definidos, devem coincidir |
| Reivindicações (opcional) | name | Nome de exibição mostrado a outros participantes, com até 80 caracteres |
| Reivindicações (opcional) | role | host, cohost, participant, panelist ou attendee |
| Reivindicações (opcional) | permissions, canPublish | O que o participante pode publicar, conforme a solicitação de token REST |
| Reivindicações (opcional) | metadata | Sua própria sequência de caracteres, de até 1 KB, visível para outros participantes |
| Reivindicações (opcional) | ttlSeconds | Vigência das credenciais de mídia retornadas pela troca: de 30 a 300 |
| Reivindicações (opcional) | transcribe | false: 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.
Node.js (jose)
Seção intitulada “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)
Seção intitulada “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"]})
Troque um token de conexão
Seção intitulada “Troque um token de conexão”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.
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.