Перейти к содержимому
Разделы документации

PWA

Как создать токен для интеграции

Создание безопасного токена для REST, MCP и webhooks: выбор scopes, подключение, срок действия и отзыв.

Обновлено Версия 2

#Как создать токен для интеграции

Integration token позволяет подключить к Balvanchik внешний сервис или ИИ-агента через REST, MCP либо webhooks. Доступ токена ограничивается выбранными scopes.

Создание и отзыв токенов — серверные операции. Для них нужны подключение к интернету и активный вход в аккаунт.

#Создать токен

  1. Откройте меню пользователя.
  2. Перейдите в Настройки → Интеграции.
  3. Укажите понятное название, например название сервиса или агента.
  4. Выберите необходимые scopes.
  5. При необходимости задайте срок действия.
  6. Нажмите «Создать токен».

#Выбрать scopes

Выдавайте только тот доступ, который действительно нужен интеграции:

ScopeВозможности
readЧтение доступных задач, проектов, меток и других данных через REST или MCP.
writeСоздание и изменение данных. Для обычных изменений через MCP обычно нужны одновременно read и write.
mcpПодключение MCP-клиента и вызов доступных ему инструментов.
webhooksСоздание, просмотр и удаление webhook-подписок.

Примеры:

  • для REST-интеграции только на чтение выберите read;
  • для ИИ-агента выберите mcp, read и write;
  • для управления webhooks через REST выберите webhooks, а через MCP — mcp и webhooks.

#Сохранить полное значение

После создания Balvanchik показывает полное значение с префиксом bvk_ только один раз. Сразу скопируйте его в защищённое хранилище секретов.

Не добавляйте токен в Git-репозиторий, исходный код, скриншоты или общедоступные логи. Если значение потеряно, восстановить его нельзя: отзовите старый токен и создайте новый.

#Подключить REST

Используйте базовый адрес:

https://api.balvanchik.ru

Передавайте токен в каждом запросе:

Authorization: Bearer bvk_...

Доступные маршруты, обязательные поля и заголовки опубликованы в OpenAPI-схеме.

#Подключить MCP

Укажите в MCP-клиенте endpoint:

https://api.balvanchik.ru/mcp

Токен передаётся как Bearer token. Scope mcp разрешает подключение, read открывает инструменты чтения, а сочетание read и write — обычные инструменты создания и изменения данных.

#Подключить webhooks

Для управления подписками нужен scope webhooks. Подписки можно создавать через REST либо через MCP-клиент с дополнительным scope mcp.

В production webhook должен использовать HTTPS. Секрет подписи новой подписки также показывается только при её создании.

#Срок действия и отзыв

Если срок действия не указан, токен не истекает автоматически. После указанной даты доступ прекращается.

Чтобы отключить интеграцию раньше:

  1. Откройте Настройки → Интеграции.
  2. Найдите нужный токен.
  3. Нажмите «Отозвать» и подтвердите действие.

Отозванный токен сразу перестаёт работать в REST, MCP и webhooks. Если подключение не работает, проверьте scopes, срок действия и статус токена.

Как создать токен для интеграции в Balvanchik | balvanchik