Federated with Better Auth

Better Auth runs inside your app and against your own database. 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 Better Auth supplies

One value: session.user.id. That is the external_id.

lib/better-auth.ts

import "server-only";

import { headers } from "next/headers";

import { auth } from "./auth";

export async function currentExternalId(): Promise<string | null> {
  const session = await auth.api.getSession({ headers: await headers() });
  return session?.user.id ?? null; // ← the external_id
}

getSession validates against the database rather than decoding the cookie. Here the temptation is at its strongest, because the session table is right there — but an id the browser could choose is not something to sign.

The server half

app/api/userkit-boot/route.ts

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

import { currentExternalId } from "@/lib/better-auth";

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" };

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 Better Auth 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
`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`	Better Auth’s own configuration, all server-side

What does not travel

Better Auth’s user carries email and emailVerified. They are statements about your database, 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 Better Auth

What Better Auth supplies

The server half

The client half

Configuration

What does not travel

The full example

​What Better Auth supplies

​The server half

​The client half

​Configuration

​What does not travel

The full example

What Better Auth supplies

The server half

The client half

Configuration

What does not travel