Autenticación

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

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, 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) — y te devuelve el conjunto EFECTIVO de scopes de tu clave, para que nunca tengas que adivinarlo:

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.