Widget Token

El Widget Token autentica las llamadas que hace el widget a /api/widget/* desde el navegador del comprador. Lo emite tu servidor y lo inyectas en el <script> del CDN.

Cabecera

X-Widget-Token: <token>

Naturaleza del token

El token es una cadena Base64 que codifica shopId:timestamp:firma-HMAC-SHA256. Lo firma nuestro backend usando tu Shop API Key como secreto, lo que garantiza que solo nosotros podemos emitir tokens válidos. La validación HMAC ocurre en cada request: si alguien manipula la cadena, el backend rechaza con 401.

Para tu cliente JavaScript el token es opaco: pásalo como data-token y el widget lo envía como X-Widget-Token en cada llamada. No necesitas verificar la firma ni inspeccionar el contenido — eso es trabajo del backend.

Cómo emitir un token

POST /api/shops/{shopId}/widget-token autenticado con tu Shop API Key:

curl -X POST https://api.neuroon.ai/api/shops/$SHOP_ID/widget-token \
  -H "X-Shop-API-Key: $NEUROON_API_KEY"

Respuesta (status 200):

{
  "token": "c2hvcF9hYmM6MTcxNTAwMDAwMDoxYTJiM2M..."
}

El payload del response es exactamente { "token": string }. No incluye expiresAt — el TTL es fijo: 24 horas desde la emisión.

Tiempo de vida

• Validez: 24 h (app.widget.token-validity-seconds = 86400 en el backend).
• No es renovable: para tener uno nuevo, vuelves a llamar al mismo endpoint.
• Rotación recomendada: cada 23 h con un margen de 1 h. Cachea el último token y su timestamp de emisión en tu servidor; cuando hayan pasado más de 23 h, vuelve a llamar al endpoint antes del próximo render.

Inyección en el HTML

Server-side (cualquier framework: Next.js, Razor, PHP, Express, Rails…):

<div id="neuroon-search"></div>
<script
  src="https://cdn.neuroon.ai/widget.js"
  data-token="<%= widgetToken %>"
  data-container="#neuroon-search"
  data-theme="auto">
</script>

Sustituye <%= widgetToken %> por la sintaxis de tu motor de plantillas. El token ya está cacheado en tu servidor; aquí solo lo imprimes.

Errores

Código	Causa	Acción
401 Unauthorized sin cabecera	Falta X-Widget-Token	El widget la añade solo; revisa que data-token esté presente
401 Unauthorized con token	Firma inválida o token modificado	Emite un token nuevo desde tu servidor
401 Unauthorized tras 24 h	Token expirado	Llama otra vez al endpoint de emisión
403 Forbidden con Origin mismatch	Navegador llama desde un dominio que no coincide con shop.url ni con app.widget.allowed-origins	Añade el dominio al shop o verifícalo

Buenas prácticas

• No expongas la Shop API Key en el navegador. Esa clave es server-only y permite muchas más operaciones que el Widget Token.
• No reutilices el mismo Widget Token entre Producción y Desarrollo. Son tokens distintos firmados con secretos distintos.
• Almacena el token cifrado en el secret manager de tu stack (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, Vault, wp_options con encriptación, etc.).
• No registres tokens en logs públicos. Trátalo como dato sensible.

Próximas lecturas

• Recipe · Server-to-server token — implementaciones completas en Node, .NET, Python, PHP.
• Shop API Key — la credencial server-only que firma los tokens.
• Rate Limits — cuotas por endpoint.
• Errores — códigos, estructura, field-level errors.