Federated with Firebase

Firebase Authentication is your source of truth. UserKit needs to know which of your users is on the page, and it will not take the page’s word for it — your server signs the claim.

The identity secret never enters the bundle. Never prefix it with NEXT_PUBLIC_, never render it into HTML, never send it to the browser to save a round trip. Whoever holds it can mint a verified session for any of your users.

The contract is the one on the federated identity page and nothing here changes it:

hash = hex( HMAC-SHA256( identity_secret, external_id ) )

What Firebase supplies

One value: uid. Firebase is the provider that does not arrive as a cookie your server can read — the browser holds an ID token and sends it, and a token is a string anybody can compose. verifyIdToken is what turns it into a fact.

lib/firebase.ts

import "server-only";

import { getAuth } from "firebase-admin/auth";

export async function currentExternalId(idToken: string | null): Promise<string | null> {
  if (!idToken) return null;
  try {
    const decoded = await getAuth(admin()).verifyIdToken(idToken);
    return decoded.uid; // ← the external_id
  } catch {
    return null;
  }
}

user.uid is also sitting in the browser, and it is deliberately not what gets sent. An id the page supplies is an id the page chose — signing it would let any visitor be anyone.

The server half

app/api/userkit-boot/route.ts

import { createHmac } from "node:crypto";
import { NextResponse, type NextRequest } from "next/server";

import { currentExternalId } from "@/lib/firebase";

export const dynamic = "force-dynamic";
// The Admin SDK is a Node library; it does not run on the edge runtime.
export const runtime = "nodejs";

export async function GET(request: NextRequest) {
  const header = request.headers.get("authorization") ?? "";
  const idToken = header.toLowerCase().startsWith("bearer ") ? header.slice(7) : null;

  const externalId = await currentExternalId(idToken);
  if (!externalId) {
    return NextResponse.json({ error: "not_signed_in" }, { status: 401, headers: NO_STORE });
  }

  const hash = createHmac("sha256", process.env.USERKIT_IDENTITY_SECRET!)
    .update(externalId)
    .digest("hex");

  return NextResponse.json({ external_id: externalId, hash }, { headers: NO_STORE });
}

// This body identifies one person. A CDN that kept it would hand the next
// visitor a proof of somebody else's identity.
const NO_STORE = { "Cache-Control": "no-store" };

An ID token that will not verify answers 401, exactly as an absent one does. The difference is a detail about your verification that the browser has no use for.

The client half

"use client";

import { createClient } from "@userkit/js";

const userkit = createClient({
  publishableKey: process.env.NEXT_PUBLIC_USERKIT_PUBLISHABLE_KEY!,
});

const user = getAuth().currentUser;

if (!user) {
  // Still a visitor. An anonymous boot is where first-touch attribution lands.
  await userkit.boot();
} else {
  const response = await fetch("/api/userkit-boot", {
    cache: "no-store",
    headers: { Authorization: `Bearer ${await user.getIdToken()}` },
  });
  const { external_id, hash } = await response.json();
  await userkit.boot({ externalId: external_id, hash });
}

getState().verified is true only when the HMAC checked out. Signed in to Firebase with verified: false means either the secret belongs to the other environment or the message signed was not exactly the external_id.

Session cookies work too

createSessionCookie is the other shape, and it makes this endpoint look like the Supabase one: read the cookie, verify it with verifySessionCookie, sign the uid. Nothing above the provider line changes.

Configuration

Variable	Where it lives
`USERKIT_IDENTITY_SECRET`	Server only. `GET /v1/organization/environments/{id}/identity`, per environment
`NEXT_PUBLIC_USERKIT_PUBLISHABLE_KEY`	The browser. It identifies the environment and authenticates nothing
The service account (`project_id`, `client_email`, `private_key`)	Server only. What the Admin SDK verifies with
The Firebase web config	The browser. The `apiKey` identifies a project and authenticates nothing

What does not travel

A Firebase ID token carries an email and an email_verified claim. They are statements about Firebase’s records, and they do not become identities in UserKit: an email sent through /v1/boot is stored as an attribute, does not resolve to an existing contact and does not become an identity edge. The HMAC proves the external_id and only the external_id. To prove an address, send a magic link or an email code — the two flows that arrive in it.

The full example

A runnable Next app with these files, an .env.example and the pieces this page leaves out.

Get started

Core concepts

Customer authentication

Guides

Federated with Firebase

What Firebase supplies

The server half

The client half

Session cookies work too

Configuration

What does not travel

The full example

​What Firebase supplies

​The server half

​The client half

​Session cookies work too

​Configuration

​What does not travel

The full example

What Firebase supplies

The server half

The client half

Session cookies work too

Configuration

What does not travel