API documentation
API authentication
Create an IotaBot API key, choose its permissions, limit it to websites, channels and IP addresses, and roll it without downtime.
Every request carries a secret API key in the Authorization header:
Authorization: Bearer ib_live_…Keys start with ib_live_ so secret scanners — and people reading a log — recognise a leaked one. IotaBot stores only a hash of each key: the secret is shown once, when it is created or rolled.
Permissions
A key does only what its permissions allow; anything else is refused with 403 insufficient_scope. Give each system the least it needs.
| Permission | Allows |
|---|---|
conversations:read | List and read conversations — without the message text |
messages:read | Read the messages in a conversation, and delivery status |
messages:send | Send messages and upload attachments (uses the monthly API quota) |
conversations:write | Close, reopen, assign, tag, hand to a human or back to the AI |
contacts:read / contacts:write | Read / create and update contacts |
webhooks:manage | Read the webhook delivery log and replay deliveries |
Limiting a key
- Websites and channels — a key can be limited to some websites and to some channels. Anything outside them behaves as if it did not exist.
- IP allowlist — requests from any other address are refused with
403 ip_not_allowed. - Expiry — an optional date after which the key stops working.
Rolling a key
Rolling issues a new secret and can keep the old one working for up to 7 days, so you can deploy the new secret before the old one stops. Revoking takes effect immediately.