Toda petición a `/public/v1/*` se autentica con la cabecera **`X-API-Key`** — nunca con
`Authorization: Bearer`, ni con cookie de sesión:

```bash
curl https://api.aymaragents.com/public/v1/leads \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA"
```

Una clave se ve completa **una sola vez**, al crearla (guía **[Claves de API](/guides/claves-api/)**,
apartado 4); a partir de ahí, en cualquier lista solo se muestra su prefijo (`aa_xxxxxxxx…`).

## Catálogo de scopes

Cada recurso tiene dos scopes independientes — lectura y gestión (crear/actualizar). Una clave sin el scope
exacto que exige el endpoint recibe `403 PERMISSION_DENIED`, aunque tenga el resto de sus permisos:

| Recurso | Lectura | Gestión |
| --- | --- | --- |
| Leads | `tenant:leads.read` | `tenant:leads.manage` |
| Contactos | `tenant:contacts.read` | `tenant:contacts.manage` |
| Conversaciones | `tenant:conversations.read` | `tenant:conversations.manage` |
| Citas | `tenant:appointments.read` | `tenant:appointments.manage` |
| Tickets | `tenant:tickets.read` | `tenant:tickets.manage` |

`GET /public/v1/me` no exige ningún scope propio — solo una clave válida de un tenant con plan elegible (ver
[Planes y límites](/api/plans-and-limits/)) — y te devuelve el conjunto EFECTIVO de scopes de tu clave, para
que nunca tengas que adivinarlo:

```bash
curl https://api.aymaragents.com/public/v1/me -H "X-API-Key: aa_TU_CLAVE_COMPLETA"
```

Marca los scopes que necesites en el paso **«Personalizar»** al crear la clave (guía de Claves de API,
apartado 7) — el recorte queda sellado en ese momento, no se amplía después: para añadir un scope hay que
revocar la clave y crear una nueva.

## Qué NO puede hacer nunca una clave

- **Nada fuera de los 5 recursos de arriba.** No existe ruta pública para facturación, equipo, ajustes,
  integraciones, agentes IA ni administración — sea cual sea el scope de la clave, esas acciones simplemente
  no tienen endpoint bajo `/public/v1`.
- **Ver o tocar datos de otro tenant.** Una clave está ligada a un único tenant; un `id` de otro tenant en
  cualquier ruta responde `404`, indistinguible de "no existe" (nunca `403`, que confirmaría su existencia).
- **Iniciar sesión en la interfaz web** de la Plataforma — la clave autentica llamadas a la API, no un login
  de persona.

## Rotación de claves

Hoy no existe un endpoint de rotación atómica. Para rotar una clave: crea una nueva con los mismos scopes,
actualiza el secreto en tu integración y **luego** revoca la antigua (guía de Claves de API, apartado 9) —
hay una ventana breve con ambas activas, sin invalidación instantánea de la vieja al crear la nueva.

## Orígenes permitidos

`allowed_origins` (configurable al crear la clave) es una defensa contra el abuso desde un navegador — se
comprueba solo cuando la petición trae cabecera `Origin`. Una llamada servidor-a-servidor, el uso principal
de esta API, normalmente no la envía y pasa igual aunque la lista esté restringida: no la trates como el
mecanismo de autenticación, solo como una capa extra.