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

# Autenticar las solicitudes a la API de DeltaLead con la clave

> DeltaLead autentica todas las solicitudes a la API con una clave enviada en el header X-API-Key: dónde encontrarla y cómo usarla de forma segura.

DeltaLead protege todos sus endpoints con autenticación por clave de API. Cada solicitud a `https://platform-api.deltalead.ai/v1` debe incluir la clave de API en el header `X-API-Key`; sin ella, la solicitud se rechaza de inmediato, antes de cualquier procesamiento. No hay cookies, sesiones ni flujos OAuth para el acceso servidor a servidor: una clave válida en el header es todo lo que hace falta.

## Obtener la clave de API

<Steps>
  <Step title="Abrir la configuración de claves de API">
    En el panel de DeltaLead, hacer clic en el nombre de la cuenta, arriba a la derecha, y luego ir a **Configuración → Claves de API**.
  </Step>

  <Step title="Generar una clave nueva">
    Hacer clic en **Generar nueva clave** y asignarle una etiqueta descriptiva (por ejemplo, `production-crm-sync` o `dev-testing`) para poder identificarla más adelante.
  </Step>

  <Step title="Copiar y guardar la clave de forma segura">
    La clave debe copiarse apenas aparece en pantalla y guardarse en un gestor de secretos seguro (AWS Secrets Manager, HashiCorp Vault o el equivalente de la plataforma en uso). Una vez cerrado el diálogo, ya no es posible volver a ver la clave completa.
  </Step>
</Steps>

<Warning>
  La clave de API se muestra **una sola vez**, en el momento de crearla. Si el diálogo se cierra sin copiarla, hay que revocar esa clave y generar una nueva. Las claves de API nunca deben guardarse en el código fuente, en archivos `.env` versionados ni en documentos de texto plano.
</Warning>

## Uso de la clave de API

La clave de API se envía en el header `X-API-Key` en cada solicitud. El siguiente ejemplo obtiene el listado de leads:

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

`YOUR_API_KEY` se reemplaza por la clave copiada del panel. El nombre del header no distingue mayúsculas de minúsculas, pero `X-API-Key` es la forma canónica que se usa en toda esta documentación.

La misma solicitud, escrita con librerías HTTP habituales:

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

## Respuestas de error

Si la autenticación falla, la API devuelve uno de dos códigos de error HTTP.

| Código de estado   | Significado                                                          | Causa habitual                                                                              |
| ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | La solicitud no incluyó una clave de API válida.                     | Falta el header `X-API-Key`, el valor de la clave está mal escrito o la clave fue revocada. |
| `403 Forbidden`    | La clave es válida, pero no tiene permiso para realizar esta acción. | La clave se creó con alcances restringidos que excluyen el endpoint o el método invocado.   |

El cuerpo de una respuesta `401` se ve así:

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

El cuerpo de una respuesta `403` se ve así:

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

<Tip>
  Conviene crear una clave de API por entorno (desarrollo, staging, producción) y otra por cada integración o servicio que consuma la API. Eso limita el impacto si alguna clave se ve comprometida: se revoca solo la afectada, sin interrumpir el resto de los servicios. La rotación periódica consiste en generar una clave nueva, actualizar el gestor de secretos, confirmar que el tráfico fluye correctamente y recién entonces revocar la anterior.
</Tip>

## Próximos pasos

Con la clave de API configurada y funcionando, el siguiente paso es explorar el conjunto completo de endpoints disponibles en la [referencia de la API](/api-reference/introduction): gestión de leads, disparadores de campañas, configuración de agentes y suscripciones a webhooks.