Dvina MCP

Использование доступа к API

Создавайте персональные токены доступа для скриптов и MCP-клиентов и отправляйте события своего Livespace в собственные системы с помощью вебхуков.

Открыть в Markdown

В разделе Настройки › Доступ к API можно создать персональные токены доступа, чтобы скрипт или MCP-клиент мог использовать Dvina от вашего имени. Там же администраторы могут добавить вебхуки для отправки событий Livespace в собственные системы.

Доступ к API доступен на тарифе Enterprise. Каждый участник может создавать собственные токены; раздел Вебхуки виден только владельцам и администраторам.

Создание токена

  1. Откройте Настройки и выберите Доступ к API.
  2. В разделе Персональные токены доступа выберите Создать токен.
  3. Введите Название, чтобы позже понимать, для чего используется токен.
  4. Выберите Доступ: Только чтение или Чтение и запись.
  5. Укажите, когда Истекает срок действия: Через 30 дней, Через 90 дней, Через 365 дней или Бессрочно.
  6. Выберите Создать токен.
  7. В разделе Скопируйте токен скопируйте токен и сохраните его в безопасном месте. Он отображается только один раз.

Токен действует от вашего имени в том Livespace, где вы его создали, с правами вашей текущей роли в нём. Токен с доступом Только чтение позволяет читать данные, но не добавлять и не изменять их.

Чтобы использовать токен с MCP-клиентом, см. Подключение с помощью API-ключа вместо OAuth.

Просмотр, перевыпуск и отзыв токена

Ваши токены перечислены в разделе Персональные токены доступа с указанием уровня доступа. Выберите токен, чтобы увидеть его начальные символы в поле Начинается с, уровень Доступа, дату Последнего использования и дату, когда Истекает срок действия.

  • Чтобы заменить токен, выберите Перевыпустить…, затем Перевыпустить для подтверждения. Новый токен заменит прежний, а старый сразу перестанет работать. Скопируйте новый токен в разделе Скопируйте токен.
  • Чтобы отключить токен, выберите Отозвать…, затем Отозвать для подтверждения. Всё, что использует этот токен, сразу перестанет работать.

Создание, перевыпуск и отзыв токена фиксируются в журнале аудита.

Добавление вебхука

Вебхук отправляет события Livespace — те же записи, что и в журнале аудита, — на указанный вами адрес.

  1. В разделе Настройки › Доступ к API, в подразделе Вебхуки, выберите Добавить вебхук.
  2. Введите Название и URL. Используйте общедоступный HTTPS URL.
  3. Оставьте поле События пустым, чтобы получать все события, или перечислите действия и области, например member.added или sharing.*.
  4. Выберите Добавить.
  5. В разделе Скопируйте секрет подписи скопируйте секрет. Он отображается только один раз.

Если Dvina сообщает Этот адрес недоступен из Dvina, используйте общедоступный HTTPS URL.

Проверка подписи каждого запроса

Dvina отправляет события пакетами в формате JSON и подписывает каждый запрос. Используйте секрет подписи, чтобы проверить, что запрос поступил от Dvina:

  • Каждый запрос содержит заголовок X-Dvina-Signature вида t=<timestamp>,v1=<signature>.
  • Подпись — это HMAC-SHA256 в шестнадцатеричном формате, вычисленный с вашим секретом подписи для последовательности из временной метки, точки и тела запроса.
  • Вычислите подпись самостоятельно и сравните её с полученной. Отклоните запрос, если подписи не совпадают или временная метка слишком старая.

Просмотр и изменение вебхука

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

  • Чтобы изменить вебхук, отредактируйте его Название, URL или События, затем выберите Сохранить.
  • Чтобы приостановить отправку, выключите Отправлять события. Включите этот параметр снова, чтобы возобновить отправку.
  • Чтобы проверить работу вебхука, посмотрите его Статус и количество событий в поле Отправлено. Если вебхук работает с ошибкой, отображается его Последняя ошибка. Dvina продолжает попытки отправки и записывает сбой в журнал аудита.
  • Чтобы изменить секрет подписи, выберите Новый секрет подписи…, затем подтвердите действие. Запросы сразу начинают подписываться новым секретом, поэтому немедленно обновите его на стороне получателя.
  • Чтобы удалить вебхук, выберите Удалить…, затем Удалить для подтверждения. Отправка событий на него прекращается.