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

# Autenticación en la API

> Encabezado X-API-Key, rate limiting y consentimiento de detección de fraude

Todas las peticiones a los endpoints de integración deben incluir:

| Encabezado     | Obligatorio             | Descripción           |
| -------------- | ----------------------- | --------------------- |
| `X-API-Key`    | Sí                      | API Key de su cliente |
| `Content-Type` | Sí (cuando haya cuerpo) | `application/json`    |

La autenticación de las rutas de integración usa **solo API Key**; no se requiere API Secret.

## Respuesta ante credenciales inválidas

Si la API Key falta o es incorrecta, la API responde **401 Unauthorized**:

```json theme={null}
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing X-API-Key header"
}
```

Posibles mensajes: `"Missing X-API-Key header"`, `"Invalid API key"`.

## Cliente suspendido o inactivo

Si su cliente está suspendido o en onboarding, recibirá **403 Forbidden** con detalle en el campo `detail`.

## Consentimiento de detección de fraude (Ley 1581)

Las rutas de scoring (`POST /score`, `POST /score/batch`) requieren que su cliente tenga **`fraud_detection_consent=true`** configurado en Kairo Connect.

* No hay encabezado de consentimiento que usted deba enviar.
* Si el consentimiento no fue otorgado, scoring responde **403** con: `"Fraud detection consent not granted for this client."`

## Rate limiting

Kairo Shield aplica un límite de peticiones por minuto por API Key (configurable por cliente). En las respuestas se incluyen:

| Encabezado              | Descripción                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Máximo de peticiones por ventana (60 s)   |
| `X-RateLimit-Remaining` | Peticiones restantes en la ventana actual |
| `X-RateLimit-Reset`     | Segundos hasta reinicio de la ventana     |

Si excede el límite, recibirá **429 Too Many Requests** con encabezado `Retry-After: 60`.