Skip to main content

​
Backend token widget authentication

Backend token authentication ties the widget session to your existing auth system. Your backend HMAC-signs a token per user with the Notifizz Node SDK, and the frontend passes it (with userId and userEmail) to the widget. Notifizz recomputes the HMAC server-side and accepts the session only if they match.

​
TL;DR

  • Server-side: const token = client.generateHashedToken(userId) — SHA-256 of userId + authSecretKey.
  • Client-side: widget options include authType: 'backendToken', token, userId, userEmail.
  • Identity proof: Notifizz recomputes the hash with its own authSecretKey and compares — no external IDP roundtrip.
  • Recommended for production when you have your own auth and don’t already use Firebase.

​
How it works

1

User logs in

Your app authenticates the user through your existing system.
2

Backend mints the token

Call client.generateHashedToken(userId) from the Notifizz Node SDK. It returns the hex-encoded SHA-256 of userId + authSecretKey.
3

Token shipped to frontend

Return the token alongside the login response or expose a dedicated /me/notifizz-token endpoint.
4

Widget authenticates

The frontend passes token, userId, userEmail to the widget. Notifizz recomputes the hash and accepts the session if it matches.

​
Backend setup

import { NotifizzClient } from "@notifizz/nodejs";

const client = new NotifizzClient(
  process.env.NOTIFIZZ_AUTH_SECRET_KEY,
  process.env.NOTIFIZZ_SDK_SECRET_KEY,
);

// In your login endpoint or session handler:
const token = client.generateHashedToken("u_42");
return res.json({ notifizzToken: token, userId: "u_42", userEmail: "alice@example.com" });
generateHashedToken() is deterministic — the same userId always produces the same token until you rotate authSecretKey. It does not perform a network call. The Java and PHP SDKs expose the same helper: 
String token = client.generateHashedToken("u_42");

$token = $client->generateHashedToken('u_42');

​
Frontend setup

<NotifizzInbox
  options={{
    apiKey: "YOUR_FRONT_API_KEY",
    authType: "backendToken",
    token: tokenFromBackend,
    userId: "u_42",
    userEmail: "alice@example.com",
  }}
/>

​
Required fields

FieldTypeDescription
authType'backendToken'Mandatory literal.
tokenstringThe output of client.generateHashedToken(userId).
userIdstringMust match the userId you passed to generateHashedToken.
userEmailstringThe user’s email address.

​
Security

Never expose authSecretKey on the frontend. Token generation happens server-side only. The frontend only ever sees the resulting token.
The token is bound to the userId it was minted for — an intercepted token only unlocks that user’s inbox, not anyone else’s. Rotate authSecretKey (in the dashboard) when you suspect compromise; all previously minted tokens become invalid and your backend will mint new ones on the next session.

​
FAQ

Environment settings → API keys. There are two server-side keys: authSecretKey (for generateHashedToken) and sdkSecretKey (for track()). Don’t confuse them — using the wrong one yields a 401 when the widget tries to authenticate.
No. The token is deterministic by design — it’s a function of userId + authSecretKey. Anyone who has the token can act as that user, but cannot derive a token for another user. Rotate authSecretKey to invalidate existing tokens.
Notifizz accepts a short overlap window where both the old and the new key are valid (configurable in the dashboard). Mint with the old key, deploy your backend to mint with the new key, wait the overlap window, retire the old key. Existing widget sessions stay alive.
Most likely the userId you passed to the widget doesn’t match the userId you passed to generateHashedToken. Double-check both — even a string-vs-number mismatch breaks the hash. Inspect state.errorCode for a typed signal.
Yes — generateHashedToken is a pure SHA-256 computation, no network call. It runs fine in any serverless runtime that has the Notifizz Node SDK installed (or you can implement the same hash manually — see the SDK source).
Yes — the token is stable for as long as authSecretKey doesn’t rotate. Many apps cache it in a session cookie or localStorage and re-mint only on rotation. Don’t share it across origins.

​
See also

Authentication overview

The four-mode model and when to pick each.

Node.js SDK reference

Full reference for generateHashedToken() and the rest of the API.

Firebase auth

Skip the backend work if you use Firebase Auth.

Publicly-signed JWT

Decouple widget auth from your backend with a managed IDP.