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

# Authenticate DeltaLead API Requests with Your API Key

> DeltaLead authenticates all API requests using an API key passed in the X-API-Key header. Learn how to find your key and use it securely.

DeltaLead uses API key authentication to protect every endpoint. Every request you make to `https://platform-api.deltalead.ai/v1` must include your API key in the `X-API-Key` header — without it, the request is rejected immediately before any processing occurs. There are no cookies, sessions, or OAuth flows for server-to-server API access; a valid key in the header is all you need.

## Getting your API key

<Steps>
  <Step title="Open API Keys settings">
    In the DeltaLead dashboard, click your account name in the top-right corner, then go to **Settings → API Keys**.
  </Step>

  <Step title="Generate a new key">
    Click **Generate New Key**. Give the key a descriptive label (for example, `production-crm-sync` or `dev-testing`) so you can identify it later.
  </Step>

  <Step title="Copy and store the key securely">
    Copy the key immediately after it appears on screen and store it in a secure secret manager (such as AWS Secrets Manager, HashiCorp Vault, or your platform's equivalent). You will not be able to view the full key again after closing this dialog.
  </Step>
</Steps>

<Warning>
  Your API key is displayed **only once** at the moment of creation. If you navigate away or close the dialog without copying it, you must revoke the key and generate a new one. Never store API keys in source code, `.env` files committed to version control, or plain-text documents.
</Warning>

## Using your API key

Pass your API key in the `X-API-Key` header on every request. The example below retrieves your leads list:

```bash theme={null}
curl https://platform-api.deltalead.ai/v1/leads \
  -H "X-API-Key: YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with the key you copied from the dashboard. The header name is case-insensitive, but `X-API-Key` is the canonical form used throughout this documentation.

Here is the same request using a popular HTTP client library:

<CodeGroup>
  ```python Python theme={null}
  import httpx

  client = httpx.Client(headers={"X-API-Key": "YOUR_API_KEY"})
  response = client.get("https://platform-api.deltalead.ai/v1/leads")
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://platform-api.deltalead.ai/v1/leads", {
    headers: {
      "X-API-Key": "YOUR_API_KEY",
    },
  });
  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  $ch = curl_init("https://platform-api.deltalead.ai/v1/leads");
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY"]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```
</CodeGroup>

## Error responses

If authentication fails, the API returns one of two HTTP error codes.

| Status code        | Meaning                                                               | Common cause                                                                                    |
| ------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The request did not include a valid API key.                          | The `X-API-Key` header is missing, the key value is misspelled, or the key has been revoked.    |
| `403 Forbidden`    | The key is valid but does not have permission to perform this action. | The key was created with restricted scopes that exclude the endpoint or method you are calling. |

A `401` response body looks like this:

```json theme={null}
{
  "error": "unauthorized",
  "message": "Missing or invalid API key. Include your key in the X-API-Key header."
}
```

A `403` response body looks like this:

```json theme={null}
{
  "error": "forbidden",
  "message": "Your API key does not have permission to access this resource."
}
```

<Tip>
  Create a separate API key for each environment (development, staging, production) and for each integration or service that calls the API. This limits the blast radius if a key is ever compromised — you revoke only the affected key without disrupting other services. Rotate keys on a regular schedule by generating a new key, updating your secret manager, confirming traffic flows correctly, and then revoking the old key.
</Tip>

## Next steps

Now that your API key is set up and working, explore the full set of available endpoints in the [API Reference](/en/api-reference/introduction) — including leads management, campaign triggers, agent configuration, and webhook subscriptions.