01
Authentication#
Send the bi_ key as a Bearer token. BotInbox stores only a SHA-256 hash of each key, so it can't show a key again after creation, and records when each key was last used.
curl https://botinbox.dev/v0/me -H "Authorization: Bearer $BOTINBOX_API_KEY"02
Scopes#
Every key belongs to one organization (or Hobby account) and sees only its resources. An account key reaches everything in the organization; a pod key only the inboxes in its pod; an inbox key a single inbox; a domain key only the Email API for one sending domain. Managing API keys, domains, pods, and webhooks through the API requires an account-scoped key; narrower keys receive 403 with code insufficient_scope.
03
Full and sending access#
Keys have full access by default. A key with sending permission can only send (through the Email API, or from its inbox or pod) and read the status of the emails it sent. It can't list inboxes, read mail, or manage domains, webhooks or keys, and gets 403 insufficient_scope if it tries. Use sending keys on app servers, where a leaked key should be able to do as little as possible.
curl https://botinbox.dev/v0/api-keys -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" -H "Content-Type: application/json" -d '{"name":"App server","permission":"sending"}'04
Keys and roles#
A key acts with the role of the member who created it, checked on every request. Owners and Admins can create account, pod, and inbox keys and see or revoke every key in the organization. Users can create pod and inbox keys only for pods they're assigned to, and see only their own keys. Billing users can't hold keys at all. If a member is removed, their keys stop working; if a User loses access to a pod, their keys for it stop working. Refused keys get 403 with code role_forbidden.
05
Create and revoke#
Create keys in the dashboard (Keys & webhooks) or with POST /v0/api-keys, and revoke with DELETE /v0/api-keys/:keyId. Raw values are returned only at creation.
curl https://botinbox.dev/v0/api-keys -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" \
-H "Content-Type: application/json" -d '{"name":"Support agent","pod_id":"pod_123"}'Note