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/*
Shop API Key	X-Shop-API-Key	sk_<32hex>	Permanente (hasta rotación)	Tu servidor	/api/plugin/shops/*

Flujo del Widget Token (frontend)

1. Tu servidor firma el Widget Token localmente con la Shop API Key como secreto HMAC (Base64URL(shopId:unixTimestamp:HMAC-SHA256(...))). Ver Recipe · Server-to-server token.
2. Cachea el token (~23 h) y lo inyecta como data-token en el <script> que sirve tu HTML.
3. El widget envía el token en cada request al backend como X-Widget-Token.
4. 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 Shop API Key (server-to-server)

1. Generas una sk_<32hex> en el Dashboard.
2. La guardas en tu secret manager.
3. En cada request a /api/plugin/shops/{shopId}/* incluyes:

X-Shop-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Si la petición trae Origin (es un navegador), el backend valida que coincida con tu shop.url registrado. Si no coincide → 403 Forbidden.
5. Si la petición no trae Origin/Referer (HTTP client server-to-server: .NET HttpClient, curl, requests, axios desde Node), se permite.

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
403 Forbidden con Origin mismatch	El navegador envía un Origin que no coincide con shop.url
403 Forbidden cross-tenant	La sk_* corresponde a otro shopId que el de la URL
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.
• Shop API Key — formato, Origin validation, rotación.
• Rate Limits — cuotas por endpoint y backoff.
• Errores — códigos, estructura, field-level errors.