API keys and scopes
Every API key carries a scopes array that limits which operations and tools the key can invoke. Scopes are enforced server-side on every call: a key with only read cannot send SMS or place calls even if it tries.
Scopes
| Scope | Allows |
|---|---|
read | Read-only tools: list calls, list SMS, search leads, get account, list and get receptionists. |
send_sms | Send SMS. Opt-outs are enforced server-side on every send; consent gating beyond that (TCPA prior-relationship rules) is your responsibility. |
make_call | Start outbound voice calls. |
book | Create or update bookings. |
write_crm | Update CRM notes and contact records. |
write_data | Push rows of your own data into one data source you created, through POST /api/v1/data-sources/:id/ingest. The request also needs that source's ingest secret, so this scope alone writes nothing. |
manage_webhooks | Create, list, delete and test your own webhook subscriptions. Nothing else. |
admin | Admin-scoped operations (for example, webhook subscription CRUD). Never granted to MCP keys. |
* | Wildcard (legacy keys). Equivalent to every concrete scope. |
Pick the scopes when you create the key
Creating a key in the dashboard shows a checklist of what the key may do. Reading your data is always on and cannot be turned off. Everything else is off until you tick it: booking, sending SMS, writing to your CRM, sending custom data, and managing your own webhooks. A read-only key is the default, so tick nothing to get one.
Ticking send_sms asks you to confirm you have consent to text the people this key will reach. The server enforces that confirmation, not just the screen.
A key minted through POST /api/v1/keys without a scopes array falls back to ["read", "send_sms", "book"]. Legacy keys (minted before scopes existed) carry ["*"].
Keys cannot mint other keys
There is no API endpoint for creating API keys. Key creation and revocation happen only in the dashboard at Settings > Integrations, behind your dashboard login. A leaked API key therefore cannot be used to mint new keys.
Scope errors
If a key lacks the scope an operation requires, the API returns 403 with a clear error body. Ask the account owner for a key with the needed scope; see Errors for the response format.