domains / software-engineering / clerk-auth-implementation / clerk-auth

clerk-auth

Skill card

combined

The two copies cover different, non-overlapping material. The first is a generic wrapper that defers to an external detailed guide and lists trigger phrases. The second is a specific, versioned implementation guide covering Clerk API Keys beta, Next.js 16 proxy.ts middleware, API version 2025-11-10 breaking changes, and error prevention. Neither copy contains the other's core steps, so crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

---
name: clerk-auth
description: Clerk auth implementation patterns, middleware, organizations, webhooks, user sync, and breaking change prevention.
---

# Clerk Authentication

## When to Use
- Adding authentication, sign in, sign up, or user management
- Multi-tenancy, organizations, SSO, or single sign-on
- Clerk API keys, Next.js middleware, or webhook verification
- Troubleshooting JWKS, CSRF, JWT, or token-type-mismatch errors

## Prerequisites
- @clerk/nextjs@6.36.7+, @clerk/backend@2.29.2+, @clerk/clerk-react@5.59.2+
- For Next.js 16: @clerk/nextjs@6.35.0+ required

## Implementation Steps

### 1. Next.js Middleware Setup
- For Next.js 15 and earlier: use `middleware.ts`
- For Next.js 16+: use `proxy.ts` (NOT `middleware.ts`)
- Import `clerkMiddleware` from `@clerk/nextjs/server`
- Configure matcher to exclude static assets and include API routes

### 2. API Keys (Beta, Dec 2025)
- Add `<APIKeys />` component from `@clerk/nextjs` for self-service management
- Verify API keys using `verifyToken` from `@clerk/backend`
- Check `tokenType === 'api_key'` in middleware to distinguish from session tokens

### 3. Async auth() (Next.js v6+)
- Use `await auth()` instead of synchronous `auth()`
- Use `await auth.protect()` in middleware

### 4. API Version 2025-11-10 Migration
- Update endpoint URLs from `/commerce/` to `/billing/`
- Rename `payment_source` to `payment_method`
- Remove deprecated fields: `amount`, `currency`, `payer_type`, etc.
- Update SDK to v6.35.0+

### 5. Force Password Reset
- Use `clerkClient.users.updateUser(userId, { passwordDigest: 'compromised' })`

## Validation
- Test with 424242 OTP for development
- Verify webhook signatures
- Check token types in middleware
- Confirm no middleware bypass via `x-middleware-subrequest` header

## Limitations
- Do not treat output as a substitute for environment-specific validation
- Stop and ask for clarification if required inputs or success criteria are missing