Saltar al contenido principal

Widget Token

TL;DR. El Widget Token es una credencial runtime con TTL 24 h que tu servidor (no Neuroon) genera y entrega al widget en data-token. Hay dos formas de obtenerlo: botón del Dashboard (rápido, manual) o firmarlo en tu servidor con la Shop API Key (automatizado, recomendado en producción). No vive en .env y no se obtiene llamando a la API pública de Neuroon.

Cabecera​

X-Widget-Token: <token>

Naturaleza del token​

El Widget Token es una cadena opaca firmada con tu Shop API Key. Vive 24 h y solo autoriza al widget a llamar al backend. Para tu cliente JavaScript es opaco — pásalo como data-token y el widget lo envía como X-Widget-Token en cada request.

Cómo obtenerlo​

Opción A — Dashboard (manual)​

  1. Abre Dashboard → Tiendas y entra en la tienda.
  2. Pulsa Generar widget token.
  3. Copia el token y pégalo en tu HTML como data-token.
  4. Repite cada 24 h.

Útil para entornos de desarrollo, demos o sitios estáticos. En producción, prefiere la opción B para no depender de un humano cada día.

Opción B — Firma server-side (automatizado)​

Tu servidor firma el token localmente usando tu Shop API Key como secreto HMAC. No necesita llamar a Neuroon. El backend valida la firma en cada petición.

Formato del token:

Base64URL( shopId : unixTimestamp : HMAC-SHA256(hex)( "shopId:unixTimestamp", secret = shopApiKey ) )
  • shopId: tu Shop ID (shop_xxx…).
  • unixTimestamp: marca temporal en segundos (UTC).
  • La firma se calcula sobre la cadena shopId:unixTimestamp usando tu Shop API Key.
  • El token completo es la concatenación con : codificada en Base64 URL-safe (sin padding =). El backend también acepta Base64 estándar (con +, /, =) — usa el que te resulte más cómodo en tu stack.

El backend de Neuroon recalcula la firma con la Shop API Key que tiene en su BD para tu shop y comprueba que unixTimestamp esté dentro de las últimas 24 h.

Implementaciones canónicas con cache + rotación: Recipe · Server-to-server token.

Inyección en el HTML​

Server-side (cualquier framework):

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

Sustituye <%= widgetToken %> por la sintaxis de tu motor de plantillas.

Tiempo de vida​

  • Validez: 24 h desde que firmaste el unixTimestamp.
  • No es renovable: para tener uno nuevo, vuelves a firmar.
  • Rotación recomendada: cada 23 h con margen de 1 h. Cachea el último token y su issuedAt en tu servidor; cuando hayan pasado >23 h, vuelve a firmar antes del próximo render.

Errores​

CódigoCausaAcción
401 Unauthorized sin cabeceraFalta X-Widget-TokenEl widget la añade solo; revisa que data-token esté presente
401 Unauthorized con tokenFirma inválida o token modificadoVuelve a firmar (o regenera desde el Dashboard)
401 Unauthorized tras 24 hToken expiradoVuelve a firmar
403 Forbidden con Origin mismatchEl navegador llama desde un dominio que no coincide con shop.url ni con la lista de dominios "trusted"Edita shop.url en el Dashboard o pide a soporte que añadan el dominio

Buenas prácticas​

  • No expongas la Shop API Key en el navegador. Es server-only y firma todos los Widget Tokens.
  • No reutilices el mismo Widget Token entre Producción y Desarrollo. Tu Shop API Key es distinta por entorno.
  • Cachea el token en cache (Redis o memoria del proceso), no en un secret manager. Los secret managers son para credenciales long-lived como tu sk_*. Cache TTL ~23 h + recompute on miss.
  • Tampoco lo metas en variables de entorno ni en config estática (appsettings.json, .env, wp-config.php). Caduca en menos de un día y tu integración se rompe sola.
  • No registres tokens en logs públicos. Trátalo como dato sensible mientras vive.

Próximas lecturas​

Última actualización en