> ## Documentation Index
> Fetch the complete documentation index at: https://notifizz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification Widget Auth Modes

> Four widget auth modes — Firebase, backend token, publicly-signed JWT, none. Three are SDK-exposed; one is dashboard-configured.

# Notification widget auth modes

Authentication controls how the Notification Center widget identifies the current user to Notifizz. Notifizz supports four modes, three of which are picked at the call site via `authType`. The fourth, `PubliclySignedJwt`, is configured server-side via the dashboard.

## TL;DR

* **Three SDK-exposed modes** — `firebase`, `backendToken`, `none` (dev-only). Pick at the call site.
* **One dashboard-configured mode** — `PubliclySignedJwt`. No SDK shorthand. The dashboard wires a JWKS URL + claims, and the widget authenticates transparently from your existing identity-provider session.
* Production uses `firebase`, `backendToken`, or `PubliclySignedJwt`. `none` is dev-only.

## The four modes

| Mode                    | SDK `authType` value | Identity source                                    | Backend work                    |
| ----------------------- | -------------------- | -------------------------------------------------- | ------------------------------- |
| **Firebase**            | `'firebase'`         | Firebase JWKS                                      | none                            |
| **Backend Token**       | `'backendToken'`     | HMAC vs `authSecretKey`                            | generate hashed token           |
| **Publicly-Signed JWT** | n/a (server-side)    | Provider JWKS (Auth0, Clerk, Cognito, Supabase, …) | configure JWKS URL in dashboard |
| **None**                | `'none'`             | not verified                                       | none                            |

## SDK type union

Across all three frontend SDKs (`@notifizz/react`, `@notifizz/angular`, `@notifizz/vanilla`), the call-site type is:

```ts theme={null}
type AuthType = 'firebase' | 'backendToken' | 'none';
```

`PubliclySignedJwt` deliberately does not appear here — keeping the SDK surface minimal lets operators swap the strategy without a frontend deploy.

<Note>
  In the backend codebase the publicly-signed-JWT strategy is named `CustomRsaJwt`. Same mode, different name. Customer-facing docs always say **`PubliclySignedJwt`**; you may see `CustomRsaJwt` once in dashboard logs and internal tools.
</Note>

## Common SDK fields

All three frontend SDKs accept the same authentication fields:

| Option      | Type                                     | Required                       | Description                                                                                                                                                              |
| ----------- | ---------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `apiKey`    | `string`                                 | always                         | Front API Key from the dashboard.                                                                                                                                        |
| `authType`  | `'firebase' \| 'backendToken' \| 'none'` | always                         | The SDK-exposed strategy.                                                                                                                                                |
| `token`     | `string`                                 | for `firebase`, `backendToken` | Auth token.                                                                                                                                                              |
| `userId`    | `string`                                 | for `backendToken`, `none`     | The user's **stable, opaque id** — the value recipients are matched against for inbox delivery. Use your internal id, **not the email** (the email goes in `userEmail`). |
| `userEmail` | `string`                                 | for `backendToken`, `none`     | The user's email address.                                                                                                                                                |

When the configured server-side strategy is `PubliclySignedJwt`, the widget reads the JWT from your existing identity-provider session — no SDK fields beyond `apiKey` are required from your code.

## Pick a mode

<CardGroup cols={2}>
  <Card title="Firebase" icon="fire" href="/docs/sdks/authentication/firebase">
    Zero-work if you already use Firebase Auth — pass the ID token straight to the widget.
  </Card>

  <Card title="Backend Token" icon="lock" href="/docs/sdks/authentication/backend-tokens">
    Recommended for custom auth systems — your backend HMAC-signs a token per user.
  </Card>

  <Card title="Publicly-Signed JWT" icon="shield" href="/docs/sdks/authentication/publicly-signed-jwt">
    Auth0, Clerk, Cognito, Supabase Auth — configured in the dashboard.
  </Card>

  <Card title="No authentication" icon="lock-open" href="/docs/sdks/authentication/no-auth">
    Local development only — never ship to production.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Which mode should I pick first?">
    If you already use Firebase Auth, pick **Firebase** — it's a one-line frontend change. Otherwise pick **Backend Token** — it's the standard "I have my own auth" path. If you use a managed identity provider (Auth0, Clerk, Cognito, Supabase Auth), **Publicly-Signed JWT** is the better long-term choice but requires dashboard setup.
  </Accordion>

  <Accordion title="Why isn't `PubliclySignedJwt` in the SDK type?">
    Because the strategy is decided per-environment and changing it shouldn't require a frontend deploy. The dashboard owns the JWKS URL, expected issuer, and expected audience — your code just initialises the widget. This keeps the SDK surface to three options and pushes config decisions to operators rather than developers.
  </Accordion>

  <Accordion title="I see `CustomRsaJwt` in the dashboard logs.">
    Same thing as `PubliclySignedJwt` — the backend originally named the strategy `CustomRsaJwt` and the rename hasn't propagated everywhere. Treat them as identical.
  </Accordion>

  <Accordion title="Can I switch modes without a frontend redeploy?">
    Between `firebase` / `backendToken` / `none` — no, those are explicit `authType` values in your call site. Between any SDK mode and `PubliclySignedJwt` — yes, since `PubliclySignedJwt` is server-side. Many teams ship `backendToken` initially and switch to `PubliclySignedJwt` later.
  </Accordion>

  <Accordion title="`backendToken` vs `PubliclySignedJwt` — security trade-off?">
    Both are cryptographically strong. `backendToken` requires your backend to be online to mint tokens; `PubliclySignedJwt` decouples Notifizz from your backend (the widget verifies against the provider's JWKS). Pick `PubliclySignedJwt` if you want widget auth to keep working through partial backend outages, or to reduce the surface area of your `authSecretKey`.
  </Accordion>

  <Accordion title="Do I really have to use `none` in production for cost reasons?">
    No — `firebase`, `backendToken`, and `PubliclySignedJwt` add zero per-call cost. The only reason to use `none` is local development. Anyone with the API key and a `userId` can read that user's inbox in `none` mode — never ship it to production.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Authentication concept" icon="key" href="/docs/concepts/authentication">
    The four-mode model in conceptual terms.
  </Card>

  <Card title="Backend tokens" icon="lock" href="/docs/sdks/authentication/backend-tokens">
    `client.generateHashedToken()` end-to-end.
  </Card>

  <Card title="Firebase auth" icon="fire" href="/docs/sdks/authentication/firebase">
    Pass a Firebase ID token to the widget.
  </Card>

  <Card title="Publicly-signed JWT" icon="shield" href="/docs/sdks/authentication/publicly-signed-jwt">
    Auth0 / Clerk / Cognito / Supabase setup.
  </Card>
</CardGroup>