Skip to main content

​
Authentication Overview

The ColdSend Public API uses API keys for authentication. All requests must include a valid API key in the X-API-Key header.

​
Authentication Method

Include your API key in every request: 
import requests

headers = {"X-API-Key": "cs_live_your_api_key_here"}
response = requests.get(
    "https://api.coldsend.io/api/public/v1/campaigns",
    headers=headers
)

curl -H "X-API-Key: cs_live_your_api_key_here" \
  https://api.coldsend.io/api/public/v1/campaigns

​
Key Format

API keys follow this format: 
cs_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
  • cs_live_ - Prefix identifying this as a production API key
  • The remainder is a cryptographically secure random token

​
Key Security

API keys are stored securely:
  • Keys are hashed using SHA-256 before database storage
  • Raw keys are only visible during initial creation
  • Keys can be revoked at any time from the dashboard

​
Authentication Errors

​
Missing API Key

{
  "detail": "API key required"
}
Status: 401 Unauthorized This error occurs when the X-API-Key header is missing from the request.

​
Invalid or Revoked Key

{
  "detail": "Invalid or revoked API key"
}
Status: 401 Unauthorized This error occurs when:
  • The key does not exist
  • The key has been revoked
  • The key format is invalid

​
Insufficient Permissions

{
  "detail": "Missing API key scopes: campaigns:write"
}
Status: 403 Forbidden This error occurs when the key lacks the required scope for the operation. See Scopes for details.

​
Next Steps