API Key Scopes
Scopes define what actions an API key can perform. Each scope grants access to specific endpoints and operations.
Available Scopes
| Scope | Description |
|---|
campaigns:write | Create, update, and delete campaigns |
sender_accounts:write | Add and remove sender accounts |
* | Full access to all API endpoints |
Scope names follow the pattern resource:permission. The wildcard * grants all current and future permissions.
Scope Requirements
Each endpoint requires specific scopes:
| Endpoint | Method | Required Scope |
|---|
/campaigns | POST | campaigns:write |
/campaigns/{id} | PUT | campaigns:write |
/campaigns/{id} | DELETE | campaigns:write |
/sender-accounts | POST | sender_accounts:write |
/sender-accounts/{id} | DELETE | sender_accounts:write |
Scope Checking
When you make an API request, ColdSend verifies that your key has the required scope:
# Request with insufficient scope
headers = {"X-API-Key": "cs_live_key_with_sender_accounts_write_only"}
# This will succeed
requests.post(f"{base_url}/sender-accounts", headers=headers, json={...})
# This will fail with 403
requests.post(f"{base_url}/campaigns", headers=headers, json={...})
Error Response
When a key lacks the required scope:
{
"detail": "Missing API key scopes: campaigns:write"
}
403 Forbidden
Wildcard Scope
The * scope grants full access to all API endpoints:
{
"name": "Full Access Key",
"scopes": ["*"]
}
- Administrative integrations
- Development and testing
- Internal tools that need broad access
The wildcard scope grants complete API access. Only use it when necessary and protect these keys accordingly.
Best Practices
Principle of Least Privilege
Grant only the minimum scopes required:
# For a campaign automation tool
scopes = ["campaigns:write"]
# For a sender account provisioning tool
scopes = ["sender_accounts:write"]
# For a full integration
scopes = ["campaigns:write", "sender_accounts:write"]
Separate Keys by Function
Create different API keys for different purposes:
| Key Name | Scopes | Use Case |
|---|
campaign-automation | campaigns:write | Creating and managing campaigns |
inbox-provisioning | sender_accounts:write | Onboarding new sender accounts |
analytics-readonly | None (future) | Read-only analytics access |
Audit Scope Usage
Regularly review which scopes your keys actually use:
- Check the “Last Used” timestamp for each key
- Review audit logs for scope usage patterns
- Remove unused scopes or revoke unused keys
Future Scopes
Additional scopes may be added for new features:
campaigns:read - View campaign details and analyticssender_accounts:read - View sender account configurationsleads:read - Access lead dataleads:write - Manage leads
Keys with the * scope will automatically have access to new endpoints as they become available.
