Manage API scopes

Least privilege

Choose scopes when creating a key. Each operation in the API reference lists its required scope. Read scopes do not imply write permissions. Conversation access may include customer messages; limit access to trusted server applications.

Use conversations:read to read conversations, contacts:read for contact information, agents:read for public AI-agent configuration, team:read for team metadata and widget:read for widget configuration. Available write operations require their explicit write scope. A key cannot access platform administration, billing, session APIs or Socket.IO.

Change access safely

To change an integration’s permissions, create a replacement key with the new scopes, update the integration, test it, then revoke the old key. Check both a permitted request and a request outside the intended scope; the latter should return 403. Keep separate keys per integration so one revocation does not interrupt unrelated services.