Federated with Supabase

Supabase Auth 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 Supabase supplies

One value: user.id, the uuid on auth.users. That is the external_id.

lib/supabase.ts

import "server-only";

import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function currentExternalId(): Promise<string | null> {
  const store = await cookies();
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => store.getAll(),
        setAll: () => {},
      },
    },
  );

  const { data, error } = await supabase.auth.getUser();
  if (error || !data.user) return null;
  return data.user.id; // ← the external_id
}

getUser() and not getSession(). getSession() decodes the cookie the browser sent, so signing its contents would mean signing a value the browser chose. getUser() asks Supabase.

The server half

app/api/userkit-boot/route.ts

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

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

export const dynamic = "force-dynamic";

export async function GET() {
  const externalId = await currentExternalId();
  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" };

Signed out answers 401 rather than an empty pair: “no user” and “a user whose hash I could not compute” are different situations, and the caller’s next move differs.

The client half

"use client";

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

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

const response = await fetch("/api/userkit-boot", { cache: "no-store" });

if (response.status === 401) {
  // Still a visitor. An anonymous boot is where first-touch attribution lands.
  await userkit.boot();
} else {
  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 Supabase with verified: false means either the secret belongs to the other environment or the message signed was not exactly the external_id.

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
`NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`	Supabase’s own public pair

What does not travel

A Supabase user carries an email and an email_confirmed_at. Neither becomes an identity 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 Supabase

What Supabase supplies

The server half

The client half

Configuration

What does not travel

The full example

​What Supabase supplies

​The server half

​The client half

​Configuration

​What does not travel

The full example

What Supabase supplies

The server half

The client half

Configuration

What does not travel