Authentication

Bot token

Runtime API requests use Authorization: Bearer kcb_live_…. The token is revealed only when issued or rotated and is stored by Key Chat as a hash.

Authorization: Bearer $KEYCHAT_BOT_TOKEN

Rotation and revocation

Rotation invalidates the previous token immediately. Never expose a token in browser code, mobile apps, URLs, webhook payloads, or logs.

Webhook signature

KEYCHAT_WEBHOOK_SECRET is revealed when the webhook URL is first saved and after explicit rotation. It is separate from KEYCHAT_BOT_TOKEN: the token authorizes outbound bot calls, while the webhook secret authenticates incoming Key Chat events.

Verify HMAC SHA-256 over timestamp + "." + raw_body and compare signatures in constant time.

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

SDK practice

The Runtime token and webhook signing secret serve different purposes. One authorizes outbound API calls; the other authenticates incoming events.

After rotation, replace the secret atomically and restart consumers. Never emit full credentials in logs or error messages.

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!);