Credentials and scopes
Keep each agent within its organization, project and number grants.
Create server-side API keys with the minimum permissions an integration needs. The secret appears only in the creation response; subsequent reads show metadata, not the secret. Revocation is immediate for future API authentication.
| Scope family | Read | Write |
|---|---|---|
| Numbers/connections | numbers:read | numbers:write |
| Messages/conversations/media | messages:read | messages:write |
| Contacts | contacts:read | contacts:write |
| Templates | templates:read | templates:write |
| Routes | routes:read | routes:write |
| Events/replay | events:read | events:write |
| Webhook subscriptions | webhooks:read | webhooks:write |
| API keys | keys:read | keys:write |
| Organization/team/settings | organization:read | organization:write |
Scope checks apply inside shared services, including MCP calls. A read-only MCP client cannot gain write access by selecting a different tool. A credential creating another key cannot grant broader permissions than its own.
ts
const created = await client.apiKeys.create({
name: 'Orchard support', project_id: 'project_id',
number_ids: ['number_id'],
scopes: ['numbers:read', 'messages:read', 'messages:write', 'events:read'],
});
// Store created.data.secret in your server secret store. Do not log it.Customer organizations are isolated. Agency staff access clients through explicit membership; selecting another organization in the UI does not expand an API key's grants.
Prepared 18 November 2026 · Sqkii Pte. Ltd.