Getting started
Authentication
One credential for everything: an API key created in the dashboard. It works on every REST endpoint and on the MCP server, and it carries scopes that decide what it may do.
- For
- Anyone about to put a key in production
- You will need
- Dashboard access to create a key
- About
- 6 minutes to read
Creating a key
In the dashboard, go to Settings → API keys and create one. The key is shown once — it is stored only as a hash, so nobody, including us, can recover it later. If you lose it, revoke it and make another.
curl https://api.integrable.cloud/api/bots \
-H "Authorization: Bearer sk_live_your_key_here"Scopes
A key with no scopes selected has full access. A key with scopes can do exactly those things and nothing else — a call outside them is refused with 403 and a message naming the scope it wanted.
| Scope | Allows |
|---|---|
| bots:read | List assistants and read their configuration |
| bots:write | Create, update and publish assistants |
| conversations:read | Read conversations and transcripts |
| conversations:write | Claim a handoff and reply to a visitor as a human |
| contacts:read | Read captured contacts and leads |
| contacts:write | Create and update contacts |
| documents:read | List knowledge-base documents |
| documents:write | Add, reindex and remove knowledge-base documents |
| analytics:read | Read analytics, outcomes and plan usage |
| chat:write | Send a message to an assistant and get its reply |
| webhooks:read | Read endpoints and the delivery log |
| webhooks:write | Register endpoints and rotate signing secrets |
One key per integration
Keys belong to the workspace, not to the person who made them, so a key keeps working after an employee leaves. That is the right default, and it is also why a single shared key is a bad idea: when you need to revoke it, you take down everything at once.
- One key per integration, per environment, per device.
- Name them for where they run, so the list stays readable a year later.
- Give each the narrowest scopes that work.
- Set an expiry on anything temporary — a key for a contractor, or a one-off migration.
Rate limits
Each key has its own per-minute budget, so one noisy integration cannot starve another. Every response tells you where you stand:
RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 41Back off when RateLimit-Remaining gets low rather than waiting for a 429. If you do get one, it carries Retry-After in seconds.
Revoking
Delete a key in Settings → API keys. It stops working on the next call — including on any open MCP connection, which is what makes revocation mean what it says for long-lived connectors.
If a key leaks
Revoke it first, then investigate. A key can read everything in your workspace its scopes allow, so treat one pasted into a chat, a ticket or a public repository as compromised even if it looks untouched.
Tell us at security@integrable.cloud and we can help you see what it did.
Something here wrong or missing? Tell us — the documentation and the API are maintained by the same person, so a correction is a fix rather than a ticket.