/api-auth-clerk

name: api-auth-clerk
description: Clerk managed authentication - ClerkProvider, middleware, pre-built components, hooks, server-side auth, organizations, webhooks

Clerk Authentication Patterns

> **Quick Guide:** Clerk provides managed authentication with pre-built UI components, server-side helpers, and organization-based multi-tenancy. Use `clerkMiddleware()` for route protection, `<Show>` for conditional rendering, hooks for client state, and `auth()`/`currentUser()` for server-side auth. Clerk Core 3 (2026) replaces `<SignedIn>`/`<SignedOut>` with `<Show>`, renames the middleware file to `proxy.ts` (Next.js 16+), and consolidates packages.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `@clerk/nextjs/server` for ALL server-side imports -- NEVER import server helpers from `@clerk/nextjs`)**

**(You MUST verify webhooks using Clerk's `verifyWebhook` helper -- NEVER trust unverified webhook payloads)**

**(You MUST use `<Show>` component instead of deprecated `<SignedIn>`/`<SignedOut>`/`<Protect>` -- these are removed in Core 3)**

**(You MUST NOT pass the full `currentUser()` object to the client -- it contains `privateMetadata` that must stay server-side)**

**(You MUST protect routes in BOTH middleware AND data access layer -- middleware alone is insufficient)**

</critical_requirements>

---

**Auto-detection:** Clerk, ClerkProvider, clerkMiddleware, @clerk/nextjs, useUser, useAuth, useClerk, useSession, useOrganization, SignIn, SignUp, UserButton, UserProfile, OrganizationSwitcher, auth(), currentUser(), CLERK_SECRET_KEY, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, Show when="signed-in"

**When to use:**

• Adding authentication and user management to an application
• Building multi-tenant B2B apps with organization-based access control
• Using pre-built sign-in/sign-up UI components with customizable theming
• Protecting routes with middleware and server-side authorization checks
• Syncing Clerk user data to your database via webhooks

**Key patterns covered:**

• ClerkProvider setup, environment variables, middleware configuration
• Pre-built UI components (`<SignIn>`, `<SignUp>`, `<UserButton>`, `<Show>`)
• Client-side hooks (`useUser`, `useAuth`, `useSession`, `useOrganization`)
• Server-side auth (`auth()`, `currentUser()`) in Server Components, Route Handlers, Server Actions
• Middleware route protection with `clerkMiddleware()` and `createRouteMatcher()`
• Organization-based multi-tenancy with roles and permissions
• Webhook handling with Svix signature verification

**When NOT to use:**

• Self-hosted auth requirement (need full control over auth data storage)
• Cannot use a third-party auth service (compliance/regulatory constraints)
• Simple API key authentication (custom middleware is sufficient)
• Budget constraints prevent using a managed service

**Detailed Resources:**

• [reference.md](reference.md) - Decision frameworks, hooks quick reference, Core 3 migration cheat sheet
• [examples/core.md](examples/core.md) - ClerkProvider, environment variables, middleware configuration
• [examples/components.md](examples/components.md) - Pre-built components, customization, appearance prop
• [examples/hooks.md](examples/hooks.md) - useUser, useAuth, useSession, loading states, conditional rendering
• [examples/server.md](examples/server.md) - Server Components, API routes, Server Actions, webhook handling
• [examples/organizations.md](examples/organizations.md) - Organization management, roles, permissions, RBAC

---

<philosophy>

Philosophy

Clerk is a **managed authentication platform** that handles the entire auth lifecycle: sign-up, sign-in, session management, user profiles, organizations, and MFA. Instead of building auth from scratch, you integrate Clerk's SDK and pre-built components.

**Core principles:**

1. **Defense in depth** -- Protect routes at the middleware layer AND verify auth at every data access point. Middleware alone is insufficient (CVE-2025-29927 demonstrated middleware bypass vulnerabilities). 2. **Server-first auth** -- Use `auth()` and `currentUser()` in Server Components and Route Handlers. Only use client hooks (`useUser`, `useAuth`) when you need reactive client-side state. 3. **Pre-built over custom** -- Use Clerk's `<SignIn>`, `<SignUp>`, `<UserButton>` components. Only build custom flows when the pre-built components genuinely cannot meet requirements. 4. **Organizations for multi-tenancy** -- Use Clerk Organizations with roles and permissions for B2B apps. Do not build custom tenant systems on top of Clerk's user model. 5. **Webhook-driven sync** -- Sync Clerk data to your database via webhooks, not by polling. Always verify webhook signatures with `verifyWebhook`.

**When to use Clerk:**

• You need auth quickly with minimal custom code
• You want pre-built UI components for sign-in/sign-up/user management
• You need organization-based multi-tenancy with RBAC
• You want managed MFA, SSO (SAML/OIDC), and social login

**When NOT to use Clerk:**

• You need full control over auth data storage (self-hosted requirement)
• You cannot use a third-party auth service (compliance/regulatory)
• Your app only needs simple API key authentication
• Budget constraints prevent using a managed service

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: ClerkProvider and Middleware Setup

Every Clerk app needs `<ClerkProvider>` wrapping the app and `clerkMiddleware()` protecting routes. See [examples/core.md](examples/core.md) for full setup examples.

**Key rules:**

• `ClerkProvider` goes inside `<body>`, not wrapping `<html>` -- Core 3 requires this
• Use `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` env var, never hardcode keys
• Middleware file is `proxy.ts` on Next.js 16+ or `middleware.ts` on Next.js <=15
• Webhook endpoint must be in the public routes list (verified s