# Autenticación

Cada solicitud a la API debe incluir su clave de API para que <span data-t="appName">Your AI Connector</span> sepa quién es usted y sobre qué cuenta debe actuar. Puede enviar la clave de cuatro formas diferentes; todas funcionan en cualquier endpoint que acepte autenticación mediante clave de API, así que elija la que mejor se adapte a su configuración.

El acceso a la API es una función de pago. Si su plan no la incluye, las solicitudes serán rechazadas con un `403` incluso cuando la clave sea válida; consulte [La restricción de funciones de pago](#the-paid-feature-gate) a continuación. Para generar una clave, consulte [Acceso a la API](../integrations/api-access.md).

> **Solo HTTPS.** Todas las solicitudes deben utilizar una conexión segura. Las solicitudes HTTP simples son rechazadas antes incluso de que se ejecute la autenticación.

---

## Resumen de los cuatro métodos

| Método | Transportador | Cuándo usarlo |
|---|---|---|
| Parámetro de consulta | `?apiKey=YOUR_API_KEY` | Pruebas rápidas y URLs de navegador |
| Cabecera | `X-API-Key: YOUR_API_KEY` | Integraciones en producción |
| Cabecera Bearer | `Authorization: Bearer YOUR_API_KEY` | Integraciones en producción |
| Token de ID de Firebase | `Authorization: Bearer <ID token>` | Solo sesiones de aplicaciones propias |

Cuando hay más de uno presente, el parámetro de consulta tiene prioridad, seguido de la cabecera `X-API-Key` y, finalmente, el token bearer. En la práctica, solo se envía uno.

---

## 1. Parámetro de consulta — `?apiKey=`

Añada su clave al final de la dirección web. Esta es la forma más sencilla y siempre funciona, lo que la hace ideal para pruebas rápidas, scripts y cualquier herramienta antigua.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()
```

> **Aviso:** Las direcciones web quedan registradas en el historial del navegador, en los registros de acceso del servidor y en los registros de proxy. Para cualquier cosa que no sea una prueba rápida, prefiera uno de los métodos de cabecera a continuación para que su clave no se escriba en el disco a plena vista.

---

## 2. Cabecera `X-API-Key`

Envíe la clave en una cabecera dedicada. Esto la mantiene fuera de la URL y es la opción recomendada para producción.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

---

## 3. Encabezado `Authorization: Bearer`

También puede pasar la clave como un token de portador (bearer token) estándar. Esto es útil cuando su cliente o framework HTTP ya tiene soporte integrado para encabezados `Authorization`.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()
```

La API distingue automáticamente su clave de API de un token de inicio de sesión, por lo que este método funciona exactamente igual que `X-API-Key`.

---

## 4. Token de ID de Firebase (solo para aplicaciones de primera parte)

Si está creando una aplicación de primera parte que inicia sesión a los usuarios a través del propio inicio de sesión de <span data-t="appName">Your AI Connector</span>, puede pasar el token de ID de Firebase del usuario que ha iniciado sesión como un token de portador en lugar de una clave de API:

```
Authorization: Bearer <Firebase ID token>
```

El token se verifica en cada solicitud y se asigna a la cuenta que ha iniciado sesión. **Este método es solo para sesiones de aplicaciones de primera parte**: no puede crear estos tokens desde una integración externa y no hay forma de obtener uno sin pasar por el inicio de sesión normal de la aplicación. Para integraciones de servidor a servidor y de terceros, utilice una clave de API (métodos 1–3).

---

## Cuándo usar cada uno

- **Pruebas rápidas y scripts únicos** → parámetro de consulta (`?apiKey=`). Es lo más rápido de escribir y funciona en un navegador.
- **Integraciones de producción y llamadas de servidor a servidor** → `X-API-Key` o `Authorization: Bearer YOUR_API_KEY`. Mantiene la clave fuera de las URL y los registros.
- **Aplicaciones de primera parte con un usuario de <span data-t="appName">Your AI Connector</span> que ha iniciado sesión** → `Authorization: Bearer <Firebase ID token>`.

---

## Alcances de las claves

Su cuenta tiene una **clave de API principal**: la que se encuentra en **Configuración → Integraciones → Clave de API**. Tiene acceso completo a todo lo que la cuenta puede hacer.

También puede crear **claves con alcance limitado**: claves con nombre que solo acceden a las partes de la API que usted elija, por ejemplo, una clave de solo lectura limitada a Analytics para un panel de informes. Una clave con alcance limitado se envía exactamente igual que la clave principal (cualquiera de los métodos 1–3 anteriores), pero se verifica con sus propios permisos en cada solicitud:

- **Fuera de sus áreas permitidas, se rechaza.** Una escritura con una clave de solo lectura, o una llamada a una sección para la que no se otorgó la clave, devuelve un `403` — `key_read_only` o `key_scope_denied` en el campo `error_code`. La verificación es deliberadamente estricta: todo lo que no esté claramente dentro de las áreas permitidas de la clave se rechaza en lugar de permitirse, por lo que si ve uno de esos `403`, la clave simplemente no cubre ese endpoint.
- **Tiene su propio presupuesto de límite de tasa.** Una clave con alcance limitado se cuenta por separado de su clave principal, por lo que un panel de control ocupado que utilice una clave con alcance limitado no puede agotar la asignación de la que dependen sus otras integraciones. Usted elige ese presupuesto por minuto cuando crea la clave.
- **No puede administrar claves de API.** Solo el propietario de la cuenta (iniciando sesión o utilizando la clave principal) puede listar, crear, editar, rotar o revocar claves. Una clave con alcance limitado nunca puede crear una clave con mayor alcance.

Consulte [Claves de API](api-keys.md) para saber cómo crear, editar y revocar claves con alcance limitado.

---

## El control de funciones de pago

El acceso a la API es una función de pago. Cuando su plan no lo incluye, una solicitud con una clave válida se rechaza con `403`:

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

If you see this, check your plan or contact [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}
```

---

## Mantenga su clave segura

- **Trate la clave como una contraseña.** Su clave principal otorga acceso completo a su cuenta. Si necesita entregar una clave a una herramienta o a una persona que solo necesita una parte de ella, cree una clave con alcance limitado; consulte [Alcances de las claves](#key-scopes).
- **Manténgala en el lado del servidor.** Nunca la incruste en JavaScript de navegador, en un paquete de aplicación móvil o en cualquier código que un usuario final pueda leer.
- **Almacénela en un administrador de secretos** o en la configuración del lado del servidor, no en el control de código fuente.
- **Rótela si se filtra.** Genere una nueva clave desde el panel de control o llame a `POST https://api.youraiconnector.com/v1/api-keys/rotate`; esto invalida inmediatamente la anterior. Consulte [Claves de API](api-keys.md).
- **Utilice siempre HTTPS** para que la clave esté cifrada durante el tránsito.

---

## Próximos pasos

- [Introducción](getting-started.md): su primera solicitud y las guías de recursos.
- [Errores y paginación](errors-and-pagination.md): gestione los fallos y recorra los resultados por páginas.
- [Claves de API](api-keys.md): rote, revoque y compruebe el uso de su clave.