Autenticación

Toda la API pública v1 autentica con una sola cosa: el header X-API-Key. No hay tokens en la query, ni en el body, ni un segundo esquema. Una key es un workspace: cada recurso que devuelve la API queda acotado al workspace dueño de la key.

El header X-API-Key

Incluye tu key en cada request:

curl https://TU-DOMINIO/api/public/v1/leads \
  -H "X-API-Key: sygk_live_tu_api_key"

Asira no acepta Authorization: Bearer para la API pública. Si mandas la key por cualquier otro medio que no sea el header X-API-Key, recibes 401.

Formato de la key

Las keys llevan el prefijo sygk_live_ seguido de material aleatorio. Por ejemplo: sygk_live_9f8a7b6c5d4e3f2a1b0c….

En el servidor solo se guarda el hash SHA-256 de la key, el texto plano nunca se persiste. Por eso la key se muestra una única vez al crearla: si la pierdes, no se puede recuperar, hay que crear una nueva. Se guarda también un prefijo corto (los primeros caracteres) para poder identificarla en la UI sin exponer el secreto.

Crear una key

Abre Configuración → API
Necesitas rol de administrador o manager del workspace.
Crea la key y cópiala
Pon un nombre descriptivo (ej. "n8n producción", "landing web"). Al crearla se muestra una sola vez: cópiala y guárdala en un secret manager o variable de entorno.
Úsala en el header
A partir de ahí, manda X-API-Key: sygk_live_… en cada request.

La key es un secretoNunca la subas a git, no la incrustes en el front (es visible para el usuario), no la pegues en logs. Trátala como una contraseña.

Revocar una key

Desde Configuración → API puedes revocar cualquier key. La revocación es inmediata: a partir de ese momento todo request con esa key devuelve 401. Si una integración deja de funcionar con 401 unauthorized, revisa que la key no haya sido revocada y, si hace falta, crea una nueva y actualiza la integración.

Para rotar una key sin cortar el servicio: crea la nueva, actualiza la integración, y recién entonces revoca la vieja.

Límite de uso

Cada key tiene un límite de 5000 requests por día. El contador se resetea a medianoche (UTC). Al superarlo, los siguientes requests devuelven 429 con código rate_limited hasta el reset.

Si necesitas más volumen, distribuye la carga en varias keys o pide un ajuste de límite al equipo.

Envelope de error

Todos los errores de la API pública tienen la misma forma:

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o revocada."
  }
}

code: código estable en snake_case (no cambia entre versiones; puedes ramificar tu lógica sobre él).
message: texto legible en español (para logs o humanos; puede cambiar).

Códigos frecuentes

HTTP	code	Cuándo
`401`	`unauthorized`	Falta el header X-API-Key, o la key es inválida o revocada.
`429`	`rate_limited`	Se alcanzó el límite diario de 5000 requests de esa key.
`404`	`not_found`	El recurso no existe o no pertenece a tu workspace.
`422`	`validation_error`	El body o los parámetros no pasan validación.
`500`	`internal_error`	Error interno al procesar el request.

Por seguridad, una key inexistente y una revocada devuelven exactamente el mismo 401 unauthorized: la API no revela si una key existió alguna vez.