Autenticación
Neuroon expone dos credenciales según desde dónde llamas a la API. Elige la que corresponde al origen de la petición; no son intercambiables.
¿Cuál uso?
Tabla comparativa
| Mecanismo | Cabecera | Formato | TTL | Origen | Endpoints |
|---|---|---|---|---|---|
| Widget Token | X-Widget-Token | Cadena opaca | 24 h | Navegador | /api/widget/* |
| API Key | Authorization: Bearer <key> | Bearer token | Permanente (hasta rotación) | Tu servidor | /api/integrations/v1/* |
Flujo del Widget Token (frontend)
- Tu servidor firma el Widget Token localmente con la API Key como secreto HMAC (
Base64URL(shopId:unixTimestamp:HMAC-SHA256(...))). Ver Recipe · Server-to-server token. - Cachea el token (~23 h) y lo inyecta como
data-tokenen el<script>que sirve tu HTML. - El widget envía el token en cada request al backend como
X-Widget-Token. - Cuando hayan pasado >23 h, tu servidor vuelve a firmar y rota el token sin downtime.
Para casos manuales (demo, dev), también puedes generar un Widget Token desde Dashboard → Tiendas → "Generar widget token". El cliente JavaScript no firma nada: el token es opaco y la firma se valida server-side en cada request.
Flujo de la API Key (server-to-server)
- Obtienes tu API Key desde el Dashboard de Neuroon (shop settings).
- La guardas en tu secret manager.
- En cada request a
/api/integrations/v1/*incluyes:
Authorization: Bearer <api-key>
- La API key está vinculada a una tienda específica — no necesitas incluir
shopIden la URL. El backend resuelve la tienda automáticamente. - Las llamadas deben ser server-to-server. Si se detecta un
Originde navegador, el backend rechazará la petición.
Errores comunes
| Síntoma | Causa probable |
|---|---|
401 Unauthorized con cabecera presente | Token expirado, mal formado o de otro entorno |
401 Unauthorized sin cabecera | Olvidaste poner el header Authorization: Bearer ... |
404 Not Found | Shop no encontrada para esta API key |
402 Payment Required | Cuota excedida — upgrade your plan |
422 Unprocessable Entity | ID de search log no encontrado o expirado (conversiones) |
429 Too Many Requests | Rate limit excedido — ver Retry-After |
Detalle de cada uno: Errores.
Próximas lecturas
- Widget Token — emisión, rotación, uso.
- API Key — obtención, almacenamiento, rotación.
- Rate Limits — cuotas y backoff.
- Errores — códigos, estructura, field-level errors.