Keys and permissions

Format and where to send it

Live keys start with bk_live_, test keys with bk_test_; a key enabled for Push is spelled bt_live_, the shape the Push plane reads, and every other module accepts both. The middle part is the key id (you will see it in logs and on the key page); the tail is the secret, stored only as a hash and shown once. Send the whole key as a bearer token.

curl "https://api.bolrach.com/send/v1/status" \
  -H "Authorization: Bearer bk_live_your_key_here"

A test key drives the same endpoints against test data (Send's sandbox sender, Bot's sandbox runtime); the modules refuse a test key on a live path and a live key whose prefix claims otherwise.

Modules and permissions

A key holds a list of scopes. Each scope is module:permission; module:* grants everything in one module. The hub offers these as named presets (send transactional mail, read conversations, manage apps) and writes the scopes for you.

What a key acts as

Send, Bot and Push are workspace products, so a key enabled for one of them is bound to your workspace or tenant at creation: a Send key sends as your Send workspace, a Bot key reaches the bots of your Bot workspace (or one bot, when minted from that bot's page), a Push key acts for your Push tenant. The gateway services (Identity, Trust, Wiki, Geo and the rest) need no binding.

Expiry, allowlists and rate

• Expiry. Optional, set at creation (30, 90 or 365 days). An expired key answers 401 until rotated.
• Sending domains. A Send key may be locked to the domains it can send from.
• Source addresses. A key may be limited to a list of IPs or prefixes; other addresses get 401.
• Rate. A per-key limit per minute where the module supports it (Bot today); otherwise the module's own limit applies.

Rotate and revoke

Rotating mints a new secret with the same name, modules, permissions, bindings and limits, and revokes the old one at once; the old key's record points at its successor. Revoking stops a key for good and records who did it and why. Both happen on the key page; each module caches a verdict for at most thirty seconds.

Keys made before this page

Keys minted by a module before the store was unified keep working: Send's snd_live_, Bot's bot_live_ and the developer platform's bt_ keys were imported with their hashes and appear on your keys page marked imported. They cannot be rotated in place (their secret is the whole token); create a bk_ key and revoke the old one when convenient.

Errors