Токен и права

Токен#

Токен бота выглядит так:

calab_bot_0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b_Xq3v9aT2LmN8pR4sW7yZ1bC5dF0gH6jK3nQ9uV2xE8w
└──┬────┘ └───────────────┬──────────────────┘ └────────────────┬────────────────────┘
 префикс           id бота (UUID)                  секрет: 43 символа base64url

• Префикс calab_bot_ нужен сканерам секретов (GitHub и другие), чтобы распознать утёкший токен.
• Сервер хранит только хеш sha256 секрета: показать токен повторно невозможно. В профиле бота видны первые 6 символов секрета (tokenPrefix) — чтобы отличать токены.
• Токен не истекает сам: он действует, пока его не перевыпустят или не отзовут.

Как передавать#

Никогда не передавайте токен в URL, query-строке или теле вебхука — только в этих двух местах.

curl -s https://app.example.com/api/me -H "Authorization: Bearer $TOKEN"

Перевыпуск и отзыв#

В «Настройках пространства → Боты» владелец бота или участник с правом MANAGE_BOTS в домашнем пространстве бота может:

• «Перевыпустить токен» — получить новый токен; старый перестаёт работать сразу.
• «Отозвать токен» — выключить бота без нового токена, пока его не перевыпустят.
• «Удалить бота» — бот выходит из всех пространств и звонков; его сообщения остаются.

Что происходит со старым токеном:

Один токен — один процесс#

Токен — это одно «устройство» в gateway. Второй процесс с тем же токеном вытесняет первый: сокет первого закрывается с кодом 4000 и причиной replaced by a new session. Запускайте один процесс на токен. Чтобы масштабировать обработку, используйте вебхук с идемпотентной обработкой по id или несколько ботов.

Права#

Бот — участник пространства, и его права считаются точно так же, как права человека: роли пространства плюс переопределения в комнате или на доске.

• По умолчанию бот получает роль участника: видит открытые комнаты, пишет в них, заходит в голос.
• Нужно больше — выдайте боту роль с нужными правами: MANAGE_MESSAGES для модерации, CREATE_TASKS / EDIT_TASKS для досок, INVITE_MEMBERS для приглашений и так далее.
• Нужно меньше — запретите право переопределением в комнате.
• Закрытые комнаты и доски бот видит только через переопределение на самом объекте — личное или по роли, как и человек. Иначе — 404.

Каждая глава REST-раздела перечисляет права, которые нужны для её маршрутов. Если права нет, сервер отвечает 403 FORBIDDEN, а message называет недостающее право.

Бот с правами администратора — администратор#

Токен бота, чьи роли дают MANAGE_*, INVITE_* или VIEW_JOURNALS, действует как администратор с этими правами. Храните такой токен как пароль администратора и перевыпускайте при малейшем сомнении. Редактор ролей предупреждает, когда административные права получает роль, которая есть у ботов. Сервер записывает в журнал каждое административное действие бота — маршрут, статус ответа, бота и его владельца.

Бот в нескольких пространствах#

Бот создаётся в одном — домашнем — пространстве; там им управляют (токен, удаление). Администратор другого пространства может добавить бота к себе: «Настройки пространства → Боты → Добавить бота из другого пространства» по его username или по ссылке /bots/<username>. В каждом пространстве права бота — свои, по его ролям там.

Блокировка людьми#

Человек может «Заблокировать бота» — тогда бот не может писать ему в личные сообщения: новые DM и сообщения в существующем DM получают 403 BOT_BLOCKED.

Что закрыто для ботов всегда#

Эти маршруты отвечают боту 403 FORBIDDEN с reason: "BOT_NOT_ALLOWED" — какие бы роли у него ни были:

Точный список маршрутов — Маршруты ботов.

Хорошие практики#

• Храните токен в секрет-хранилище (Vault, переменные окружения CI), не в коде.
• Давайте боту минимальные права: отдельная роль под задачу лучше, чем роль администратора.
• Для админских задач заведите отдельного бота — токен с широкими правами должен быть у меньшего числа процессов.
• Секрет вебхука храните отдельно от токена и проверяйте подпись каждой доставки — см. Вебхуки.