Table of Contents
Permission Scopes #
API keys use scopes to control what actions they can perform. Always grant minimum permissions needed.
Available Scopes #
| Scope | Permissions | Endpoints |
|---|---|---|
calls:read |
View calls, recordings, transcripts | GET /calls, GET /calls/:id |
calls:write |
Trigger new calls | POST /calls |
campaigns:read |
View campaigns & stats | GET /campaigns |
campaigns:write |
Create/manage campaigns | POST /campaigns, PUT /campaigns/:id |
agents:read |
View agents | GET /agents |
contacts:read |
View contacts | GET /contacts |
contacts:write |
Create/update contacts | POST /contacts, PUT /contacts/:id |
webhooks:manage |
Manage webhooks | All /webhooks endpoints |
credits:read |
View credit balance | GET /credits |
Common Scope Combinations #
Analytics Dashboard #
calls:read campaigns:read credits:read
CRM Integration #
calls:write contacts:write webhooks:manage
Marketing Automation #
campaigns:read campaigns:write contacts:read
Scope Hierarchy #
write scopes do NOT include read permissions. You need both:
Example: To trigger calls AND view call details, you need:
calls:write(to trigger)calls:read(to view results)
Testing Scopes #
Test with minimal scopes first, then add as needed:
- Start with read-only scopes
- Test your integration
- Add write scopes as required
- Document which scopes you use
Leave A Comment