Autenticación
Neuroon expone tres mecanismos de autenticación según quién hace la petición y desde dónde.
Decision tree
¿Quién está llamando a la API?
├── Es un navegador (widget embebido)
│ └── X-Widget-Token (TTL 24 h, opaco, emitido por Neuroon)
│ Endpoints: /api/widget/*
│
├── Es tu servidor (cualquier stack)
│ └── X-Shop-API-Key (formato sk_<32hex>, permanente hasta rotación)
│ + validación de Origin (no-Origin = server-to-server permitido)
│ Endpoints: /api/plugin/shops/*
│
└── Búsqueda pública (catálogo cross-shop, uso anónimo)
└── JWT OAuth2 (usuario autenticado en plataforma Neuroon)
o anonymous (rate-limited)
Endpoints: /api/search/*
Tabla comparativa
| Mecanismo | Cabecera | Formato | TTL | Quién lo usa | 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/* |
| JWT OAuth2 | Authorization: Bearer ... | JWT firmado | Configurable | Apps autenticadas / anónimo | /api/search/* |
Diagramas de flujo
Widget Token (frontend)
1. Tu equipo emite un Widget Token en el Dashboard de Neuroon
2. Lo embebes en data-token de la <script> del CDN
3. El widget lee el token y lo envía como X-Widget-Token en cada request
4. Backend valida: firma + expiración + alcance
5. Si expira: regenera desde el Dashboard (o automáticamente vía tu backend)
El cliente no firma nada con HMAC. El token es opaco y emitido por Neuroon.
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}/* añades:
X-Shop-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
4. Si la petición viene con Origin (browser): el backend valida que coincida
con shop.url. Si no coincide -> 403.
5. Si la petición no trae Origin/Referer (cliente server-to-server: .NET HttpClient,
curl, Python requests, axios desde Node): se permite.
JWT OAuth2 (público / autenticado)
Las rutas de /api/search/* aceptan tanto JWT firmado por nuestro proveedor de identidad como llamadas anónimas (con rate limit estricto). Este mecanismo está pensado para experiencias de catálogo cross-shop, no para integración de tu tienda.
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 plan y backoff.
- Errores — códigos, estructura, field-level errors.