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	The backend SDKs send it for you: in the body of event tracking calls, and as `Authorization: Bearer <sdkSecretKey>` on the identity calls.
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

Keys can’t be rotated from the dashboard yet. If a key needs replacing — a leak, a departure, a routine policy — contact support: the key is replaced and the old one stops working at once. Backend-side keys (SDK secret, auth secret) are read on every call, so the new key takes effect as soon as your service redeploys with it.

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. Two suspects: (1) wrong environment (most common), (2) typo / extra whitespace.

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.

What if my key leaks?

Contact support at once: the leaked key is replaced and stops working immediately. Treat a leaked SDK secret as serious — it can send events on your behalf, which trigger your campaigns, and link or unlink identities in its environment, which can show one person’s history in another’s record. Pair it with your incident process: review recent events for anything you didn’t send, and ask support to review the identity changes made with the key.

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