Ссылка для входа в Speak с ролью администратора

Kinescope позволяет заранее задать роль участника в ссылке на комнату Speak. Вы подписываете JWT-токен (JSON Web Token) на своём сервере и добавляете его к ссылке — человек открывает её и попадает в комнату сразу администратором.

Это значит, что вам не нужно выдавать права вручную в интерфейсе: роль приходит вместе со ссылкой, а решение о том, кому её отправить, принимает ваша система.

Кому подходит эта статья

• Разработчикам платформ — нужно выдавать ссылки на встречи из LMS, CRM или личного кабинета
• Backend-разработчикам — требуется подписывать токены с ролью на своей стороне
• Интеграторам вебинаров — нужно, чтобы ведущий заходил в комнату с полными правами

Когда вам нужна ссылка с ролью для Speak

Вот типичные ситуации, когда это пригодится:

• Ведущий заходит из вашего интерфейса — преподаватель нажимает «Начать урок» в вашей системе и попадает в комнату администратором
• Автоматическая рассылка ссылок — расписание встреч живёт в вашей системе, и ссылки для ведущих генерируются без участия человека
• Несколько ведущих в одной комнате — правами управляет ваша система, а не владелец комнаты
• Без ручной выдачи прав — никто не назначает роли в интерфейсе Speak перед каждой встречей

Если хотя бы один из этих сценариев вам знаком — читайте дальше.

Как работает вход по ссылке с ролью (4 шага)

Схема та же, что и в чате трансляций: асимметричная криптография RSA, приватный ключ остаётся у вас.

1. Вы создаёте пару ключей (приватный и публичный) на вашем сервере
2. Публичный ключ сохраняется в Kinescope через API (приватный остаётся только у вас)
3. Ваш сервер создаёт JWT-токен с полями aud, room_id и role и подписывает его приватным ключом
4. Пользователь открывает ссылку с токеном — Kinescope проверяет подпись публичным ключом и пускает его в комнату с указанной ролью

Теперь разберём, как это настроить.

Шаг 1 — ключи для подписи

Ключи для Speak генерируются и сохраняются точно так же, как для чата трансляций. Если вы уже настраивали JWT для чата, переходите сразу к шагу 2 — новый ключ не нужен.

Что нужно сделать:

1. Сгенерировать пару ключей RSA и подготовить публичный ключ в формате JWK — генерация ключей
2. Сохранить публичный ключ в Kinescope через POST /v1/jwk — сохранение публичного ключа
3. Проверить список активных ключей при необходимости — управление ключами

Шаг 2 — токен для Speak

Создайте JWT-токен и подпишите его приватным ключом по алгоритму RS256. Идентификатор ключа передайте в заголовке токена в поле kid.

Обязательные поля

• aud (audience) — значение "speak". По нему Kinescope понимает, что токен предназначен для видеовстречи, а не для чата.
• room_id — код комнаты из её ссылки, например jqi-qhua-glk. Должен совпадать с кодом в адресе, по которому пойдёт пользователь.
• role — роль участника. Сейчас поддерживается значение "admin" — участник получает права администратора комнаты.

Где взять код комнаты: он стоит в конце ссылки на комнату в интерфейсе Speak. Через API его вернут поля code и link в ответе GET /v1/speak/rooms — смотрите справочник API .

Стандартные JWT-поля (рекомендуется)

Добавьте exp, iat и nbf — они работают так же, как в чате трансляций, и проверяются при валидации токена. Подробности — в разделе стандартные JWT-поля .

Пример payload

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

Пример генерации токена

package main

import (
    "crypto/rsa"
    "time"

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

type SpeakClaims struct {
    RoomID string `json:"room_id"` // код комнаты из ссылки
    Role   string `json:"role"`    // admin
    jwt.RegisteredClaims
}

// Генерация токена для входа в комнату 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"}, // обязательно "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 сохранённого в Kinescope публичного ключа

    return token.SignedString(privateKey)
}

Общая механика подписи и примеры библиотек для других языков — в разделе пример генерации JWT .

Ссылка для входа

Добавьте готовый токен к ссылке на комнату параметром token:

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

Пример:

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

Готово! Теперь участник, открывший такую ссылку, попадёт в комнату с ролью администратора.

Безопасность

Что стоит соблюдать:

• Короткий срок жизни токена — ставьте exp на время, близкое к длительности встречи, а не на месяцы вперёд
• Генерация на бэкенде — приватный ключ не должен попадать в браузер или мобильное приложение
• Никаких токенов в логах и аналитике — ссылка с токеном не должна утекать в системы, где её увидят посторонние
• Отдельная ссылка на каждого ведущего — так проще отозвать доступ и разобраться, кто чем воспользовался

Регламент обновления ключей и действия при утечке приватного ключа описаны в статье про чат: ротация ключей и действия при компрометации ключа .

Решение проблем

Токен не принимается системой

Проблема: пользователь открывает ссылку, но не попадает в комнату или заходит без роли администратора.

Проверьте по порядку:

1. Поле aud — должно быть строго "speak" в нижнем регистре. Токен для чата ("chat") в Speak не подойдёт.
2. Поле room_id — код комнаты в токене должен совпадать с кодом в адресе ссылки. Например, для https://speak.kinescope.io/jqi-qhua-glk в токене нужен "room_id": "jqi-qhua-glk".
3. Поле role — значение "admin" в нижнем регистре.
4. Срок действия токена — проверьте exp и синхронизацию системного времени на сервере (NTP).
5. Публичный ключ — он должен быть загружен в Kinescope, не истёкшим, а токен подписан парным ему приватным ключом по алгоритму RS256.

Проверить структуру и подпись токена локально до отправки пользователю поможет пример из раздела как проверить валидность токена . Частые ошибки при работе с ключами разобраны там же, в разделе решение проблем .

Если проблема не решилась, напишите в техническую поддержку и приложите код комнаты, пример токена (чувствительные данные можно замаскировать) и описание шагов воспроизведения.

Что дальше?

После настройки ссылок с ролью рекомендуем:

1. Что такое Speak — возможности видеовстреч и запись в каталог
2. JWT-аутентификация для чата трансляций — тот же механизм ключей для чата
3. Справочник API по Speak — создание комнат, участники и звонки

Остались вопросы? Напишите в чат поддержки — специалисты помогут!