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

# Authentication Overview

> Learn how authentication works with the ColdSend Public API.

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:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests

    api_key = "cs_live_your_api_key_here"
    headers = {"X-API-Key": api_key}

    response = requests.get(
        "https://api.coldsend.pro/api/public/v1/campaigns",
        headers=headers
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const apiKey = "cs_live_your_api_key_here";

    const response = await fetch("https://api.coldsend.pro/api/public/v1/campaigns", {
      method: "GET",
      headers: {
        "X-API-Key": apiKey,
        "Content-Type": "application/json"
      }
    });

    const data = await response.json();
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -H "X-API-Key: cs_live_your_api_key_here" \
      https://api.coldsend.pro/api/public/v1/campaigns
    ```
  </Tab>
</Tabs>

## Authentication Errors

<AccordionGroup>
  <Accordion title="Missing API Key">
    ```json theme={null}
    {
      "detail": "API key required. Include your API key in X-API-Key header."
    }
    ```

    **Status:** `401 Unauthorized`
  </Accordion>

  <Accordion title="Invalid or Revoked Key">
    ```json theme={null}
    {
      "detail": "Invalid or revoked API key"
    }
    ```

    **Status:** `401 Unauthorized`
  </Accordion>

  <Accordion title="Insufficient Permissions">
    ```json theme={null}
    {
      "detail": "Missing required scopes: campaigns:write",
      "required": ["campaigns:write"],
      "granted": ["sender_accounts:read"]
    }
    ```

    **Status:** `403 Forbidden`

    This error occurs when your API key lacks the required scope. See [API Key Scopes](/authentication/scopes) for details.
  </Accordion>
</AccordionGroup>

## Best Practices

1. **Store API keys securely** — Use environment variables or a secrets manager. Never hardcode them.
2. **Use granular scopes** — Create API keys with minimal required scopes for each integration.
3. **Monitor key usage** — Review which keys are being used and revoke unused ones.
4. **Implement error handling** — Handle HTTP 401 and 403 responses gracefully.

## Next Steps

<CardGroup cols={2}>
  <Card title="Create API Keys" href="/authentication/api-keys" icon="key">
    How to create and manage API keys.
  </Card>

  <Card title="API Key Scopes" href="/authentication/scopes" icon="shield">
    Understand granular permissions.
  </Card>
</CardGroup>