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

# Firebase Notification Widget Auth

> Authenticate the Notification Center widget with a Firebase ID token — Notifizz verifies it server-side, no backend work required.

# Firebase widget authentication

If your app already uses Firebase Auth, you can authenticate the Notification Center widget directly with a Firebase ID token. Notifizz verifies the token against the Firebase JWKS server-side — no additional backend work needed on your side.

## TL;DR

* Pass `authType: 'firebase'` and a Firebase ID token to the widget.
* Notifizz verifies the token; you don't need to send `userId` or `userEmail` (they're extracted from the token).
* Firebase tokens expire after 1 hour — re-mint the widget when the SDK refreshes the token.

<Tip>
  If you don't already use Firebase Auth, [Backend Token](/docs/sdks/authentication/backend-tokens) or [Publicly-Signed JWT](/docs/sdks/authentication/publicly-signed-jwt) are the right choices. `PubliclySignedJwt` works with Auth0, Clerk, Cognito, Supabase Auth, and any provider that publishes a JWKS endpoint.
</Tip>

## How it works

```mermaid theme={null}
sequenceDiagram
    participant App as Your app
    participant Firebase
    participant Notifizz

    App->>Firebase: User signs in
    Firebase->>App: Firebase ID token
    App->>Notifizz: Mount widget with token
    Notifizz-->>Firebase: Verify token (JWKS)
    Notifizz->>App: Connected — notifications flow
```

<Steps>
  <Step title="User authenticates with Firebase">
    Your app signs the user in via any Firebase Auth provider (email/password, Google, GitHub, …).
  </Step>

  <Step title="Obtain the ID token">
    `auth.currentUser.getIdToken()` returns a fresh (or cached-still-valid) ID token.
  </Step>

  <Step title="Mount the widget">
    Pass the token to the widget as `options.token` with `authType: "firebase"`.
  </Step>

  <Step title="Notifizz verifies">
    The Notifizz backend verifies the token against the Firebase JWKS, extracts the user identity, and opens the widget session.
  </Step>
</Steps>

## Setup

<Tabs>
  <Tab title="React">
    ```jsx theme={null}
    import { getAuth } from "firebase/auth";
    import NotifizzInbox from "@notifizz/react";

    const auth = getAuth();
    const idToken = await auth.currentUser.getIdToken();

    <NotifizzInbox
      options={{
        apiKey: "YOUR_FRONT_API_KEY",
        authType: "firebase",
        token: idToken,
      }}
    />
    ```
  </Tab>

  <Tab title="Angular">
    ```typescript theme={null}
    import { Auth } from "@angular/fire/auth";

    @Component({
      template: `
        <notifizz-bell
          [options]="{
            apiKey: 'YOUR_FRONT_API_KEY',
            authType: 'firebase',
            token: firebaseToken
          }"
        ></notifizz-bell>
      `,
    })
    export class AppComponent {
      firebaseToken = "";

      constructor(private auth: Auth) {
        this.auth.currentUser?.getIdToken().then((t) => {
          this.firebaseToken = t;
        });
      }
    }
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```javascript theme={null}
    import { getAuth } from "firebase/auth";
    import { createNotifizz } from "@notifizz/vanilla";

    const auth = getAuth();
    const idToken = await auth.currentUser.getIdToken();

    const notifizz = createNotifizz({
      apiKey: "YOUR_FRONT_API_KEY",
      authType: "firebase",
      token: idToken,
    });

    notifizz.mount();
    ```
  </Tab>
</Tabs>

## Required fields

| Field      | Type         | Description                                     |
| ---------- | ------------ | ----------------------------------------------- |
| `authType` | `'firebase'` | Mandatory literal.                              |
| `token`    | `string`     | A valid Firebase ID token for the current user. |

<Info>
  In Firebase mode you do not pass `userId` or `userEmail` — Notifizz extracts the identity from the verified token. Passing them anyway is harmless (they're ignored).
</Info>

## Token refresh

Firebase ID tokens expire after 1 hour. The Firebase SDK refreshes them automatically — `auth.currentUser.getIdToken()` returns a cached token when valid, and a fresh one when expired. To keep the widget happy across the refresh boundary:

* Re-mount the widget on `onIdTokenChanged` so the new token reaches Notifizz immediately, **or**
* Call `getIdToken()` proactively before mounting (the cached path is cheap), **or**
* Let the widget surface `state.hasError = true` on expiry, then re-mount with a fresh token.

```typescript theme={null}
// Re-mount on token refresh (React)
useEffect(() => {
  return onIdTokenChanged(getAuth(), async (user) => {
    if (user) {
      const fresh = await user.getIdToken();
      setNotifizzToken(fresh);
    }
  });
}, []);
```

## Firebase vs Backend Tokens

|                               | Firebase                 | Backend Tokens                   |
| ----------------------------- | ------------------------ | -------------------------------- |
| **Already use Firebase Auth** | yes — zero extra work    | unnecessary overhead             |
| **Custom auth system**        | n/a                      | the right choice                 |
| **Backend involvement**       | none                     | mint a token per user            |
| **Token management**          | Firebase handles refresh | you manage delivery and rotation |

## FAQ

<AccordionGroup>
  <Accordion title="The widget says `hasError: true` after the user has been logged in for an hour.">
    Token expired. The Firebase SDK has a fresh one — call `getIdToken()` and re-mount the widget. The simplest pattern is to subscribe to `onIdTokenChanged` and re-mount whenever the token changes.
  </Accordion>

  <Accordion title="Can I use Firebase Auth on the backend (admin SDK) and pass that ID token?">
    Yes — any token Firebase issues for the user works. The Notifizz backend verifies via the public JWKS, so the issuer (client SDK vs admin SDK) doesn't matter as long as the JWT is valid for your Firebase project.
  </Accordion>

  <Accordion title="Multiple Firebase projects — which one does Notifizz verify against?">
    The dashboard environment settings include a Firebase project ID. Tokens issued for any other project are rejected. If you use multiple Firebase projects (e.g. dev / prod), point each Notifizz environment at its corresponding project.
  </Accordion>

  <Accordion title="Custom claims — does Notifizz read them?">
    Notifizz reads `sub` (user id) and `email`. Custom claims are visible in the campaign orchestrator if you forward them via event properties, but the widget does not consume them directly.
  </Accordion>

  <Accordion title="Should I cache the token in `localStorage`?">
    Don't cache it manually — the Firebase SDK handles caching internally and knows when to refresh. Calling `getIdToken()` is cheap when the cached token is still valid.
  </Accordion>

  <Accordion title="What about anonymous Firebase users?">
    Anonymous users have a stable `uid` and a valid ID token, so Firebase Auth mode works. The notification orchestrator may not have meaningful campaign data for an anonymous user — bridge to a real identity before depending on personalised content.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Authentication overview" icon="key" href="/docs/sdks/authentication/overview">
    The four-mode model and when to pick each.
  </Card>

  <Card title="Backend tokens" icon="lock" href="/docs/sdks/authentication/backend-tokens">
    Use this if you don't already have Firebase Auth.
  </Card>

  <Card title="Publicly-signed JWT" icon="shield" href="/docs/sdks/authentication/publicly-signed-jwt">
    Auth0, Clerk, Cognito, Supabase Auth — decouple widget auth from your backend.
  </Card>

  <Card title="Notification Center overview" icon="bell" href="/docs/sdks/notification-center/overview">
    Lifecycle, state model, custom bell, headless mode.
  </Card>
</CardGroup>