> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coldsend.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# API Key Scopes

> Understand scopes and permissions for ColdSend API keys.

Scopes define what actions an API key can perform. Each scope grants access to specific endpoints and operations.

<Info>
  Scope names follow the pattern `resource:action`. The wildcard `*` grants all current and future permissions.
</Info>

## 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. |

<Warning>
  Only use `*` for administrative tools. Protect these keys accordingly.
</Warning>

## Scope Checking

When an API request is made, ColdSend verifies the API key has the required scope:

### Success Example

```python theme={null}
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

```json theme={null}
{
  "detail": "Missing required scopes: campaigns:write",
  "required": ["campaigns:write"],
  "granted": ["sender_accounts:read"]
}
```

**Status:** `403 Forbidden`

## Best Practices

1. **Principle of least privilege** — Grant only the minimum scopes needed
2. **Separate keys by function** — Different integrations should use different keys
3. **Audit regularly** — Review which scopes your keys actually use
4. **Use compound scopes** — `campaigns:all` is cleaner than listing each scope individually

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" href="/authentication/overview" icon="shield">
    Learn how to authenticate requests using API keys.
  </Card>

  <Card title="API Keys" href="/authentication/api-keys" icon="key">
    Create and manage API keys for your integrations.
  </Card>
</CardGroup>