Авторизация

Токен бота

Runtime API принимает заголовок Authorization: Bearer kcb_live_…. Токен показывается только при выпуске или ротации и хранится на сервере в виде хэша.

Authorization: Bearer $KEYCHAT_BOT_TOKEN

Ротация и отзыв

При ротации старый токен немедленно перестаёт работать. Не помещайте токен в браузер, мобильное приложение, URL, webhook payload или журнал запросов.

Подпись webhook

KEYCHAT_WEBHOOK_SECRET выдаётся при первом сохранении webhook URL и при явной ротации. Это отдельный секрет: KEYCHAT_BOT_TOKEN авторизует исходящие запросы бота, а webhook secret подтверждает входящие события Key Chat.

Проверяйте timestamp и HMAC SHA-256 от строки timestamp + "." + raw_body. Сравнение подписи должно выполняться constant-time способом.

X-KeyChat-Timestamp: 1791748800
X-KeyChat-Signature: v1=<hex-hmac-sha256>

Практика с SDK

Runtime token и webhook signing secret — разные секреты. Первый авторизует исходящие API-запросы, второй подтверждает происхождение входящих событий.

После ротации атомарно замените секрет в хранилище и перезапустите обработчики. Никогда не выводите секрет целиком в логи или сообщения об ошибке.

import { verifyWebhook } from '@keychat/bots';

// Keep rawBody unchanged: verifyWebhook checks timestamp, HMAC and freshness.
const event = verifyWebhook(rawBody, request.headers, process.env.KEYCHAT_WEBHOOK_SECRET!);