Link de entrada no Speak com a função de administrador

O Kinescope permite definir a função do participante no link da sala Speak. Você assina um token JWT (JSON Web Token) no seu servidor e o adiciona ao link. A pessoa abre o link e entra na sala já como administrador.

Você não precisa conceder direitos na interface do Speak: a função vem com o link, e o seu sistema decide para quem enviá-lo.

Para quem é este artigo

• Desenvolvedores de plataformas — precisam emitir links de reuniões a partir de LMS, CRM ou área do usuário
• Desenvolvedores backend — precisam assinar tokens com a função no próprio servidor
• Integradores de webinars — precisam que o apresentador entre na sala com direitos completos

Quando você precisa de um link Speak com função

Casos típicos:

• O apresentador entra pela sua interface — o professor clica em «Iniciar aula» no seu sistema e entra na sala como administrador
• Envio automático de links — a agenda de reuniões vive no seu sistema, e os links para apresentadores são gerados sem uma pessoa no meio
• Vários apresentadores na mesma sala — quem controla os direitos é o seu sistema, não o dono da sala
• Sem atribuição manual de funções — ninguém define funções na interface do Speak antes de cada reunião

Se algum desses cenários é o seu, continue.

Como funciona a entrada com função (4 passos)

O esquema é o mesmo do chat de transmissões: criptografia assimétrica RSA, a chave privada fica com você.

1. Você cria um par de chaves (privada e pública) no seu servidor
2. A chave pública é salva no Kinescope pela API (a privada permanece só com você)
3. Seu servidor cria um token JWT com os campos aud, room_id e role e o assina com a chave privada
4. O usuário abre o link com o token — o Kinescope verifica a assinatura com a chave pública e o deixa entrar na sala com a função indicada

Agora a configuração.

Passo 1 — chaves de assinatura

As chaves do Speak são geradas e salvas da mesma forma que as do chat de transmissões. Se você já configurou JWT para o chat, vá direto ao passo 2. Não precisa de uma chave nova.

O que fazer:

1. Gerar um par de chaves RSA e preparar a chave pública no formato JWK — geração de chaves
2. Salvar a chave pública no Kinescope via POST /v1/jwk — salvar a chave pública
3. Listar as chaves ativas, se precisar — gerenciamento de chaves

Passo 2 — token para o Speak

Crie um token JWT e assine-o com a chave privada pelo algoritmo RS256. Passe o identificador da chave no cabeçalho do token no campo kid.

Campos obrigatórios

• aud (audience) — "speak". Com isso o Kinescope entende que o token é para a videochamada, não para o chat.
• room_id — código da sala no link, por exemplo jqi-qhua-glk. Deve coincidir com o código no endereço que o usuário abrir.
• role — função do participante. O valor suportado é "admin": o participante recebe direitos de administrador da sala.

Onde pegar o código da sala: ele fica no final do link da sala na interface do Speak. Na API ele vem nos campos code e link da resposta de GET /v1/speak/rooms — veja a referência da API .

Campos JWT padrão (recomendados)

Inclua exp, iat e nbf. Eles funcionam como no chat de transmissões e são verificados na validação. Detalhes: campos JWT padrão .

Exemplo de payload

{
  "aud": "speak",
  "room_id": "jqi-qhua-glk",
  "role": "admin",
  "iat": 1703500800,
  "exp": 1703504400
}

Exemplo de geração do token

package main

import (
    "crypto/rsa"
    "time"

    "github.com/golang-jwt/jwt/v5"
)

type SpeakClaims struct {
    RoomID string `json:"room_id"` // código da sala no link
    Role   string `json:"role"`    // admin
    jwt.RegisteredClaims
}

// Gera um token para entrar na sala Speak
func generateSpeakJWT(privateKey *rsa.PrivateKey, kid, roomID, role string) (string, error) {
    now := time.Now()

    claims := SpeakClaims{
        RoomID: roomID,
        Role:   role,
        RegisteredClaims: jwt.RegisteredClaims{
            Audience:  []string{"speak"}, // obrigatório "speak"
            IssuedAt:  jwt.NewNumericDate(now),
            ExpiresAt: jwt.NewNumericDate(now.Add(1 * time.Hour)),
        },
    }

    token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
    token.Header["kid"] = kid // Key ID da chave pública salva no Kinescope

    return token.SignedString(privateKey)
}

A mecânica da assinatura e bibliotecas para outras linguagens: exemplo de geração de JWT .

Link de entrada

Acrescente o token pronto ao link da sala no parâmetro token:

https://speak.kinescope.io/{{room_code}}?token={{jwt}}

Exemplo:

https://speak.kinescope.io/jqi-qhua-glk?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleS0yMDI0LTEyLTI1In0.eyJhdWQiOiJzcGVhayIsInJvb21faWQiOiJqcWktcWh1YS1nbGsiLCJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3MDM1MDA4MDAsImV4cCI6MTcwMzUwNDQwMH0.signature_here

Pronto. Quem abrir esse link entra na sala com a função de administrador.

Segurança

O que vale observar:

• Vida curta do token — coloque exp perto da duração da reunião, não meses à frente
• Geração no backend — a chave privada não pode ir para o navegador nem para o aplicativo móvel
• Nenhum token em logs ou analytics — o link com token não pode vazar para sistemas onde estranhos o vejam
• Um link por apresentador — fica mais fácil revogar o acesso e ver quem usou o quê

A rotação de chaves e o que fazer se a chave privada vazar estão no artigo do chat: rotação de chaves e ações quando uma chave é comprometida .

Solução de problemas

Token não aceito pelo sistema

Problema: o usuário abre o link, mas não entra na sala ou entra sem a função de administrador.

Verifique nesta ordem:

1. aud — deve ser exatamente "speak" em minúsculas. Um token de chat ("chat") não funciona no Speak.
2. room_id — o código da sala no token deve coincidir com o código no endereço. Para https://speak.kinescope.io/jqi-qhua-glk o token precisa de "room_id": "jqi-qhua-glk".
3. role — "admin" em minúsculas.
4. Validade do token — confira exp e a sincronização de relógio do servidor (NTP).
5. Chave pública — deve estar no Kinescope, não expirada, e o token assinado com a chave privada correspondente pelo algoritmo RS256.

Para conferir a estrutura e a assinatura do token localmente antes de enviar ao usuário, use o exemplo em como verificar a validade do token . Erros comuns com chaves estão em solução de problemas .

Se não resolver, escreva para o suporte . Envie o código da sala, um exemplo de token (pode mascarar dados sensíveis) e os passos para reproduzir.

O que fazer a seguir?

Depois de configurar os links com função:

1. O que é o Speak? — videochamadas e gravação no catálogo
2. Autenticação JWT para chat de transmissões — o mesmo mecanismo de chaves para o chat
3. Referência da API do Speak — salas, participantes e chamadas

Dúvidas? Escreva para o chat de suporte na interface do Kinescope.