Federado com Clerk

O Clerk é a sua fonte da verdade. O UserKit precisa saber qual dos seus usuários está na página, e não vai aceitar a palavra da página — o seu servidor assina a afirmação.

O identity secret nunca entra no bundle. Nunca prefixe com NEXT_PUBLIC_, nunca renderize no HTML, nunca mande para o navegador para economizar uma ida e volta. Quem tem esse segredo emite sessão verificada para qualquer um dos seus usuários.

O contrato é o da página de identidade federada, e nada aqui o altera:

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

O que o Clerk fornece

Um valor: userId, o id user_… que os próprios webhooks do Clerk citam. É esse o external_id.

lib/clerk.ts

import "server-only";

import { auth } from "@clerk/nextjs/server";

export async function currentExternalId(): Promise<string | null> {
  const { userId } = await auth();
  return userId ?? null; // ← o external_id
}

auth() lê a sessão que o middleware do Clerk já verificou. Decodificar o cookie __session na mão e assinar o sub dele seria assinar um valor que o navegador escolheu.

auth() exige clerkMiddleware() montado, senão ele lança em vez de responder userId nulo. Essa é a falha certa: “não consegui saber” nunca pode ser lido como “está deslogado”.

A metade do servidor

app/api/userkit-boot/route.ts

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

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

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

// Este corpo identifica uma pessoa. Um CDN que o guardasse entregaria ao próximo
// visitante a prova da identidade de outra pessoa.
const NO_STORE = { "Cache-Control": "no-store" };

A metade do cliente

"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) {
  // Continua sendo um visitante. O boot anônimo é onde a atribuição de primeiro
  // toque cai.
  await userkit.boot();
} else {
  const { external_id, hash } = await response.json();
  await userkit.boot({ externalId: external_id, hash });
}

getState().verified só é true quando o HMAC conferiu. Logado no Clerk com verified: false significa que o segredo é do outro ambiente ou que a mensagem assinada não era exatamente o external_id.

Configuração

Variável	Onde vive
`USERKIT_IDENTITY_SECRET`	Só no servidor. `GET /v1/organization/environments/{id}/identity`, por ambiente
`NEXT_PUBLIC_USERKIT_PUBLISHABLE_KEY`	No navegador. Identifica o ambiente e não autentica nada
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`	O par do Clerk — o segundo só no servidor, igual ao do UserKit

A organização do Clerk não é a identidade

orgId é uma segunda dimensão, e assinar userId + orgId numa mensagem só transformaria uma pessoa em dois contatos. O objeto de time do UserKit é o customer, resolvido por requisição a partir do X-Customer-Id — mapeie a organização do Clerk nele, não no external_id.

O que não viaja

Um usuário do Clerk carrega endereços de e-mail verificados. Eles não viram identidade no UserKit: um e-mail enviado pelo /v1/boot é guardado como atributo, não resolve para um contato existente e não vira aresta de identidade. O HMAC prova o external_id e só ele. Para provar um endereço, mande um magic link ou um código por e-mail — os dois fluxos que chegam nele.

O exemplo completo

Um app Next executável com esses arquivos, um .env.example e as partes que esta página deixa de fora.

Comece por aqui

Conceitos

Autenticação de contatos

Guias

Federado com Clerk

O que o Clerk fornece

A metade do servidor

A metade do cliente

Configuração

A organização do Clerk não é a identidade

O que não viaja

O exemplo completo

​O que o Clerk fornece

​A metade do servidor

​A metade do cliente

​Configuração

​A organização do Clerk não é a identidade

​O que não viaja

O exemplo completo

O que o Clerk fornece

A metade do servidor

A metade do cliente

Configuração

A organização do Clerk não é a identidade

O que não viaja