Authentication flow comparison

Workflow

Step 1: Set up Clerk middleware

```typescript import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isPublicRoute = createRouteMatcher([ "/", "/sign-in(.)", "/sign-up(.)", "/api/webhooks(.)", "/api/public(.)", ]);

export default clerkMiddleware(async (auth, request) => { if (!isPublicRoute(request)) { await auth.protect(); } });

export const config = { matcher: [ "/((?!_next|[^?]\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).)", "/(api|trpc)(.*)", ], }; ```

Step 2: Protect API routes with auth checks

```typescript import { auth } from "@clerk/nextjs/server"; import { NextResponse } from "next/server";

export async function GET() { const { userId, orgId, orgRole } = await auth();

if (!userId) { return NextResponse.json({ error: "Unauthorized" }, { status: 401 }); }

if (orgRole !== "org:admin") { return NextResponse.json({ error: "Forbidden" }, { status: 403 }); }

return NextResponse.json({ userId, orgId }); } ```

Step 3: Integrate Clerk JWT with Supabase RLS

```typescript import { auth } from "@clerk/nextjs/server"; import { createClient } from "@supabase/supabase-js";

export async function getAuthenticatedSupabase() { const { getToken } = await auth(); const supabaseToken = await getToken({ template: "supabase" });

if (!supabaseToken) { throw new Error("Failed to get Supabase token from Clerk"); }

return createClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, { global: { headers: { Authorization: `Bearer ${supabaseToken}` }, }, } ); } ```

```sql -- Supabase JWT function to extract Clerk user ID CREATE OR REPLACE FUNCTION auth.clerk_user_id() RETURNS TEXT AS $$ SELECT coalesce( current_setting('request.jwt.claims', true)::json->>'sub', (current_setting('request.jwt.claims', true)::json->>'userId')::text ); $$ LANGUAGE sql STABLE;

-- RLS policy using Clerk user ID CREATE POLICY "users_own_data" ON public.user_profiles FOR ALL USING (clerk_user_id = auth.clerk_user_id()); ```

Step 4: Implement RBAC with organization roles

```typescript import { auth } from "@clerk/nextjs/server"; import { NextResponse } from "next/server";

type OrgRole = "org:admin" | "org:member" | "org:viewer";

const ROLE_HIERARCHY: Record<OrgRole, number> = { "org:admin": 3, "org:member": 2, "org:viewer": 1, };

export function requireRole(minimumRole: OrgRole) { return async function checkRole() { const { userId, orgRole } = await auth();

if (!userId) {
  return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}

const userLevel = ROLE_HIERARCHY[orgRole as OrgRole] ?? 0;
const requiredLevel = ROLE_HIERARCHY[minimumRole];

if (userLevel < requiredLevel) {
  return NextResponse.json({ error: "Insufficient permissions" }, { status: 403 });
}

return null;

}; } ```

Step 5: Handle Clerk webhooks for user sync

```typescript import { Webhook } from "svix"; import { NextResponse } from "next/server"; import type { WebhookEvent } from "@clerk/nextjs/server";

const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET!;

export async function POST(request: Request) { const headerPayload = request.headers; const svixId = headerPayload.get("svix-id"); const svixTimestamp = headerPayload.get("svix-timestamp"); const svixSignature = headerPayload.get("svix-signature");

if (!svixId || !svixTimestamp || !svixSignature) { return NextResponse.json({ error: "Missing svix headers" }, { status: 400 }); }

const payload = await request.text(); const wh = new Webhook(WEBHOOK_SECRET);

let event: WebhookEvent; try { event = wh.verify(payload, { "svix-id": svixId, "svix-timestamp": svixTimestamp, "svix-signature": svixSignature, }) as WebhookEvent; } catch { return NextResponse.json({ error: "Invalid signature" }, { status: 401 }); }

switch (event.type) { case "user.created": await syncUserToDatabase(event.data); break; case "user.updated": await updateUserInDatabase(event.data); break; case "user.deleted": await deactivateUserInDatabase(event.data.id!); break; }

return NextResponse.json({ received: true }); } ```

Examples

Example 1: Protected page with org switching

```typescript import { auth } from "@clerk/nextjs/server"; import { redirect } from "next/navigation";

export default async function DashboardPage() { const { userId, orgId } = await auth();

if (!userId) redirect("/sign-in"); if (!orgId) redirect("/select-org");

const data = await fetchOrgDashboard(orgId); return <Dashboard data={data} />; } ```

Example 2: Multi-tenant RLS policy

```sql -- Organization-scoped access CREATE POLICY "org_members_access" ON public.projects FOR ALL USING ( org_id IN ( SELECT org_id FROM public.org_memberships WHERE clerk_user_id = auth.clerk_user_id() ) );

-- Admin-only write access within org CREATE POLICY "org_admins_write" ON public.org_settings FOR UPDATE USING ( EXISTS ( SELECT 1 FROM public.org_memberships WHERE org_memberships.org_id = org_settings.org_id AND org_memberships.clerk_user_id = auth.clerk_user_id() AND org_memberships.role = 'admin' ) ); ```

Decision tree

• New Next.js app → use Clerk with middleware-based auth
• Enterprise SSO requirement → use Clerk Organizations or Auth0
• Supabase data access → integrate Clerk JWT with RLS policies
• Public API → use API keys with rate limiting, not session auth
• Webhook from Clerk → verify svix signature before processing
• Multi-tenant app → use Clerk Organizations with org-scoped RLS
• Server component data fetch → use `auth()` to get user context
• If unsure about auth provider → start with Clerk for fastest iteration

Edge cases and gotchas

1. Clerk token template mismatch — the Supabase JWT template must include the `sub` claim. Verify the template in Clerk Dashboard → JWT Templates.
2. Middleware matcher too broad — matching `/(.*)` intercepts static assets and causes performance issues. Use the recommended matcher pattern.
3. Organization role caching — Clerk caches org roles in the session token. Role changes may not reflect until the token refreshes (default: 60s).
4. Webhook replay — svix handles deduplication via `svix-id`, but your handler must be idempotent for retries.
5. RLS with service role key — the Supabase service role key bypasses RLS entirely. Never expose it to the client; use the anon key with user JWTs.
6. Auth in server actions — `auth()` works in server components and route handlers but needs `await` in Next.js 15+.
7. Cross-origin auth — Clerk sessions are domain-scoped. Multi-domain setups need satellite domains or custom auth forwarding.

Evaluation criteria

• Middleware protects all non-public routes
• API routes verify `userId` before processing requests
• RBAC checks use role hierarchy, not string equality
• Supabase RLS policies reference the Clerk JWT user ID
• Webhook endpoint verifies svix signature before processing
• No auth tokens stored in localStorage (HTTP-only cookies only)
• Organization-scoped queries filter by `orgId` from the auth context
• Error responses distinguish 401 (unauthenticated) from 403 (unauthorized)
• Auth state is not duplicated between Clerk and application database
• Token refresh and session expiry are handled gracefully in the UI

Research-backed changes

The biggest delta is Authentication. Fold the concrete changes into the operating notes, then discard the fluff.

Fresh signals

• Authentication · Clerk Changelog
• B2B Authentication · Clerk Changelog
• React · Clerk Changelog
• Next.js · Clerk Changelog

Next edits

• Add one new tactic based on Authentication.
• Rewrite one stale section with today's source language.
• Turn the top signal into a reusable agent prompt.