API keys reference

Notifizz uses five distinct secrets across its surface — each scoped to a single role, each scoped per environment (dev, prod, …). This page lists them all so you know which one to copy into which place.

TL;DR

sdkSecretKey — backend → POST /v1/events/track (Bearer + body field).
authSecretKey — backend → client.generateHashedToken(userId) for widget backend-token auth.
Front API Key — frontend → widget apiKey option, used by /v1/users/auth.
webhookSigningSecret — backend → enricher constructor, verifies HMAC on incoming enricher webhooks.
verificationSecret — per-source → connectors (Segment, Stripe, HubSpot, Intercom).
All five are environment-scoped: dev keys never reach prod, and vice versa.

The five secrets

1. SDK Secret Key (`sdkSecretKey`)

Where	What
Used by	Backend SDKs (Node, Java, PHP) and any HTTP-direct caller of `POST /v1/events/track`.
Sent as	`Authorization: Bearer <sdkSecretKey>` header AND `sdkSecretKey` field in the body. Both must match.
Resolves to	The environment whose `sdkSecretKey` matches. Wrong key → `403 auth/invalid-authorization`.
Where in dashboard	Environment settings → API Keys → “SDK Secret”.

const client = new NotifizzClient(authSecretKey, sdkSecretKey);
// ↑ second arg is the SDK secret used to identify the environment.

2. Auth Secret Key (`authSecretKey`)

Where	What
Used by	Backend SDK `client.generateHashedToken(userId)`. Never sent over the wire — used to compute a SHA-256 HMAC server-side.
Lives in	Your backend env (env var, vault). Never exposed to the frontend.
Where in dashboard	Environment settings → API Keys → “Auth Secret”.

const client = new NotifizzClient(authSecretKey, sdkSecretKey);
const token = client.generateHashedToken("u_42");
// ↑ token derived from authSecretKey + userId, sent to your frontend.

3. Front API Key

Where	What
Used by	The Notification Center widget — passed as `apiKey` in the widget options.
Sent as	`apiKey` field in `POST /v1/users/auth` (the widget’s auth endpoint).
Resolves to	The environment whose Front API Key matches.
Public by design	Embedded in your frontend bundle; visible to any user.
Where in dashboard	Environment settings → API Keys → “Front API Key”.

<NotifizzInbox
  options={{
    apiKey: "YOUR_FRONT_API_KEY",
    authType: "backendToken",
    /* ... */
  }}
/>

4. Webhook Signing Secret (`webhookSigningSecret`)

Where	What
Used by	The enricher subsystem of the backend SDKs (Node, Java, PHP) — `new NotifizzClient(authKey, sdkKey, webhookSigningSecret)`.
Used for	Verifying the HMAC on inbound enricher webhooks.
Required	Only when calling `client.dispatch()`. Skip it for clients that just call `track()`.
Where in dashboard	Environment settings → Enrichers → “Webhook Signing Secret”.

The Notifizz backend signs every enricher webhook request with this secret over the verbatim payload string in the body envelope. The SDK verifies the signature on receipt. Mismatch → { ok: false, error: { code: "hmac-invalid" } } in the response body.

5. Connector Verification Secret (`verificationSecret`)

Where	What
Used by	Connector webhooks (Segment / Stripe / HubSpot / Intercom).
Per source	Each connector source has its own secret.
Used for	Notifizz verifies the per-provider HMAC on incoming webhook deliveries.
Where in dashboard	Connectors → source detail → “Webhook Signing Secret”.

The exact algorithm differs per provider — see connector webhooks.

Quick reference table

Secret	Used by	Sent over wire?	Public?	Per-environment?
`sdkSecretKey`	Backend SDKs	yes (Bearer + body)	no	yes
`authSecretKey`	Backend SDK (locally)	no	no	yes
Front API Key	Widget	yes (auth body)	yes	yes
`webhookSigningSecret`	Backend SDKs (enrichers)	no	no	yes
`verificationSecret`	Connectors	no	no	per source (and per env)

Environments

Each Notifizz organisation has multiple environments — typically dev and prod, plus optional staging or per-team environments. Each has its own copy of every secret. Never share keys across environments:

A dev sdkSecretKey posted to prod’s API resolves to dev’s environment, not prod’s — your prod traffic ends up in dev’s queue.
A prod Front API Key in your dev frontend means dev users see prod notifications.

Most failures classified as “weird” turn out to be cross-environment key contamination. Treat keys as environment-scoped from day one.

Rotation

The dashboard exposes a rotation flow per secret. The general pattern:

Generate a new key alongside the existing one (overlap window).
Deploy your services to use the new key.
Wait the overlap window — Notifizz accepts both keys during it.
Retire the old key.

Existing widget sessions keep their HMAC token across rotation only if you re-mint after the rotation; backend-side keys (SDK secret, auth secret) are read on every call, so rotation propagates as soon as your service redeploys.

Region note

The default API host is https://api.notifizz.com/v1. Future US/APAC regions will have their own hostnames; keys generated in one region don’t work against another. The dashboard surfaces the right hostname for your environment.

FAQ

I get 401 on `/events/track` — which key did I get wrong?

auth/invalid-authorization on /events/track always means the sdkSecretKey (Bearer + body) didn’t resolve to an environment. Three suspects: (1) wrong environment (most common), (2) typo / extra whitespace, (3) the key was rotated and your service hasn’t reloaded.

Where in the dashboard do I find each key?

All of them: Environment settings → API Keys (one section per role). Connector verification secrets live separately under Connectors → source detail.

Is the SDK secret safe in a mobile app?

No — never embed sdkSecretKey in a mobile or web frontend. Mobile clients should hit your own backend, which then calls Notifizz with its server-side secret. The widget’s Front API Key is the only Notifizz secret intended to ship in a frontend.

How do I rotate without downtime?

Use the dashboard rotation flow. Generate the new key, deploy your services with it, wait the overlap window (Notifizz accepts both during this period), retire the old key. Existing in-flight requests keep working — rotation only affects new requests after the cutover.

What if my key leaks?

Rotate immediately. The dashboard exposes a one-click “rotate now, no grace period” path for emergencies; this revokes the old key right away and any in-flight request using it fails. Pair it with your incident process — log audit, scan dashboard for unexpected events, etc.

Event Tracking

Where sdkSecretKey is used.

Backend tokens

Where authSecretKey is used.

Enrichers protocol

Where webhookSigningSecret is used.

Connector webhooks

Where verificationSecret is used.

Get started

Concepts

Use cases

SDKs

AI & MCP

Environments

Plans & usage

Monitor delivery

Glossary

Notifizz API Keys

API keys reference

TL;DR

The five secrets

1. SDK Secret Key (`sdkSecretKey`)

2. Auth Secret Key (`authSecretKey`)

3. Front API Key

4. Webhook Signing Secret (`webhookSigningSecret`)

5. Connector Verification Secret (`verificationSecret`)

Quick reference table

Environments

Rotation

Region note

FAQ

See also

Event Tracking

Backend tokens

Enrichers protocol

Connector webhooks

​API keys reference

​TL;DR

​The five secrets

​1. SDK Secret Key (sdkSecretKey)

​2. Auth Secret Key (authSecretKey)

​3. Front API Key

​4. Webhook Signing Secret (webhookSigningSecret)

​5. Connector Verification Secret (verificationSecret)

​Quick reference table

​Environments

​Rotation

​Region note

​FAQ

​See also

Event Tracking

Backend tokens

Enrichers protocol

Connector webhooks

API keys reference

TL;DR

The five secrets

1. SDK Secret Key (`sdkSecretKey`)

2. Auth Secret Key (`authSecretKey`)

3. Front API Key

4. Webhook Signing Secret (`webhookSigningSecret`)

5. Connector Verification Secret (`verificationSecret`)

Quick reference table

Environments

Rotation

Region note

FAQ

See also