API Key Scopes

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:update`	Update lead fields (first name, last name, company, custom fields)
`leads:delete`	Remove leads from campaigns (PENDING only)
`leads:all`	Full access to all lead operations

Replies

Scope	Description
`replies:read`	View conversations and reply threads
`replies:create`	Send replies to leads
`replies:update`	Mark threads as read or starred
`replies:all`	Full access to replies and conversations

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"]
}

Status: 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

Getting Started

Authentication

Campaigns

Sender Accounts

Domains

Leads

Replies

Analytics

Reference

Compliance

Available Scopes

Campaigns

Sender Accounts

Leads

Replies

Wildcard

Scope Checking

Success Example

Insufficient Scope Example

Best Practices

Next Steps

Authentication

API Keys

​Available Scopes

​Campaigns

​Sender Accounts

​Leads

​Replies

​Wildcard

​Scope Checking

​Success Example

​Insufficient Scope Example

​Best Practices

​Next Steps

Authentication

API Keys

Available Scopes

Campaigns

Sender Accounts

Leads

Replies

Wildcard

Scope Checking

Success Example

Insufficient Scope Example

Best Practices

Next Steps