Scopes define what actions an API key can perform. Each scope grants access to specific endpoints and operations.
Scope names follow the pattern resource:action. The wildcard * grants all current and future permissions.
Available Scopes
Campaigns
| Scope | Description |
|---|
campaigns:create | Create new campaigns |
campaigns:read | View campaign details, stats, and analytics |
campaigns:update | Modify campaign configuration |
campaigns:delete | Delete campaigns (DRAFT or PAUSED only) |
campaigns:pause | Pause active campaigns |
campaigns:activate | Resume paused campaigns |
campaigns:all | Full access to all campaign operations |
Sender Accounts
| Scope | Description |
|---|
sender_accounts:create | Add new sender accounts (ColdSend Native or SMTP) |
sender_accounts:read | View sender account details and stats |
sender_accounts:delete | Remove sender accounts |
sender_accounts:all | Full access to all sender account operations |
Leads
| Scope | Description |
|---|
leads:create | Upload leads via CSV or add individual leads |
leads:read | View lead data and engagement metrics |
leads:delete | Remove leads from campaigns (PENDING only) |
leads:all | Full access to all lead operations |
Wildcard
| Scope | Description |
|---|
* | Full access to all resources. Automatically grants access to new scopes. |
Only use * for administrative tools. Protect these keys accordingly.
Scope Checking
When an API request is made, ColdSend verifies the API key has the required scope:
Success Example
headers = {"X-API-Key": "cs_live_key_with_campaigns_read"}
response = requests.get(
f"{base_url}/api/public/v1/campaigns",
headers=headers
)
# Returns 200 OK
Insufficient Scope Example
{
"detail": "Missing required scopes: campaigns:write",
"required": ["campaigns:write"],
"granted": ["sender_accounts:read"]
}
403 Forbidden
Best Practices
- Principle of least privilege — Grant only the minimum scopes needed
- Separate keys by function — Different integrations should use different keys
- Audit regularly — Review which scopes your keys actually use
- Use compound scopes —
campaigns:all is cleaner than listing each scope individually
Next Steps
Authentication
Learn how to authenticate requests using API keys.
API Keys
Create and manage API keys for your integrations.
