Skip to main content

Authentication

Neuroon exposes two credentials depending on where the request originates. Pick the one that matches the origin of the request; they are not interchangeable.

Which one should I use?​

Comparison table​

MechanismHeaderFormatTTLOriginEndpoints
Widget TokenX-Widget-TokenOpaque string24 hBrowser/api/widget/*
API KeyAuthorization: Bearer <key>Bearer tokenPermanent (until rotation)Your server/api/integrations/v1/*

Widget Token flow (frontend)​

  1. Your server signs the Widget Token locally using the API Key as the HMAC secret (Base64URL(shopId:unixTimestamp:HMAC-SHA256(...))). See Recipe · Server-to-server token.
  2. Cache the token (~23 h) and inject it as data-token in the <script> tag served in your HTML.
  3. The widget sends the token in every request to the backend as X-Widget-Token.
  4. When >23 h have passed, your server re-signs and rotates the token with zero downtime.

For manual cases (demo, dev), you can also generate a Widget Token from Dashboard → Shops → "Generate widget token". The JavaScript client does not sign anything: the token is opaque and the signature is validated server-side on every request.

API Key flow (server-to-server)​

  1. Get your API Key from the Neuroon Dashboard (shop settings).
  2. Store it in your secret manager.
  3. In every request to /api/integrations/v1/* include:
Authorization: Bearer <api-key>
  1. The API key is bound to a specific shop — you don't need to include shopId in the URL. The backend resolves the shop automatically.
  2. Calls must be server-to-server. If a browser Origin is detected, the backend will reject the request.

Common errors​

SymptomLikely cause
401 Unauthorized with header presentToken expired, malformed, or from another environment
401 Unauthorized without headerYou forgot the Authorization: Bearer ... header
404 Not FoundShop not found for this API key
402 Payment RequiredQuota exceeded — upgrade your plan
422 Unprocessable EntitySearch log ID not found or expired (conversions)
429 Too Many RequestsRate limit exceeded — check Retry-After

Details for each: Errors.

Further reading​

Last updated on