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.
Anyone about to put a key in productionNeeds dashboard access to create a key6 minutes to read
Creating a key#
In the agent studio, go to Developer → 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/agents \
-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 |
|---|---|
| agents:read | List agents and read their configuration |
| agents:write | Create, update and publish agents |
| 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 agent 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 Developer → 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 unclear or missing? Tell us and we’ll fix it.