Clerk Auth

Clerk Auth - Breaking Changes & Error Prevention Guide

Package Versions: @clerk/nextjs@6.36.7, @clerk/backend@2.29.2, @clerk/clerk-react@5.59.2, @clerk/testing@1.13.26 Breaking Changes: Nov 2025 - API version 2025-11-10, Oct 2024 - Next.js v6 async auth() Last Updated: 2026-01-09

What's New (Dec 2025 - Jan 2026)

1. API Keys Beta (Dec 11, 2025) - NEW ✨

User-scoped and organization-scoped API keys for your application. Zero-code UI component.

// 1. Add the component for self-service API key management
import { APIKeys } from '@clerk/nextjs'

export default function SettingsPage() {
  return (
    <div>
      <h2>API Keys</h2>
      <APIKeys />  {/* Full CRUD UI for user's API keys */}
    </div>
  )
}

Backend Verification:

import { verifyToken } from '@clerk/backend'

// API keys are verified like session tokens
const { data, error } = await verifyToken(apiKey, {
  secretKey: process.env.CLERK_SECRET_KEY,
  authorizedParties: ['https://yourdomain.com'],
})

// Check token type
if (data?.tokenType === 'api_key') {
  // Handle API key auth
}

clerkMiddleware Token Types:

// v6.36.0+: Middleware can distinguish token types
clerkMiddleware((auth, req) => {
  const { userId, tokenType } = auth()

  if (tokenType === 'api_key') {
    // API key auth - programmatic access
  } else if (tokenType === 'session_token') {
    // Regular session - web UI access
  }
})

Pricing (Beta = Free):

• Creation: $0.001/key
• Verification: $0.0001/verification

2. Next.js 16: proxy.ts Middleware Filename (Dec 2025)

⚠️ BREAKING: Next.js 16 changed middleware filename due to critical security vulnerability (CVE disclosed March 2025).

Background: The March 2025 vulnerability (affecting Next.js 11.1.4-15.2.2) allowed attackers to completely bypass middleware-based authorization by adding a single HTTP header: x-middleware-subrequest: true. This affected all auth libraries (NextAuth, Clerk, custom solutions).

Why the Rename: The middleware.ts → proxy.ts change isn't just cosmetic - it's Next.js signaling that middleware-first security patterns are dangerous. Future auth implementations should not rely solely on middleware for authorization.

Next.js 15 and earlier: middleware.ts
Next.js 16+:            proxy.ts

Correct Setup for Next.js 16:

// src/proxy.ts (NOT middleware.ts!)
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

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)(.*)',
  ],
}

Minimum Version: @clerk/nextjs@6.35.0+ required for Next.js 16 (fixes Turbopack build errors and cache invalidation on sign-out).

3. Force Password Reset (Dec 19, 2025)

Administrators can mark passwords as compromised and force reset:

import { clerkClient } from '@clerk/backend'

// Force password reset for a user
await clerkClient.users.updateUser(userId, {
  passwordDigest: 'compromised',  // Triggers reset on next sign-in
})

4. Organization Reports & Filters (Dec 15-17, 2025)

Dashboard now includes org creation metrics and filtering by name/slug/date.

API Version 2025-11-10 Breaking Changes

1. API Version 2025-11-10 (Nov 10, 2025) - BREAKING CHANGES ⚠️

Affects: Applications using Clerk Billing/Commerce APIs

Critical Changes:

• Endpoint URLs: /commerce/ → /billing/ (30+ endpoints)

  GET /v1/commerce/plans → GET /v1/billing/plans
  GET /v1/commerce/statements → GET /v1/billing/statements
  POST /v1/me/commerce/checkouts → POST /v1/me/billing/checkouts

• Field Terminology: payment_source → payment_method

  // OLD (deprecated)
  { payment_source_id: "...", payment_source: {...} }
  
  // NEW (required)
  { payment_method_id: "...", payment_method: {...} }

• Removed Fields: Plans responses no longer include:

  • amount, amount_formatted (use fee.amount instead)
  • currency, currency_symbol (use fee objects)
  • payer_type (use for_payer_type)
  • annual_monthly_amount, annual_amount

• Removed Endpoints:

  • Invoices endpoint (use statements)
  • Products endpoint

• Null Handling: Explicit rules - null means "doesn't exist", omitted means "not asserting existence"

Migration: Update SDK to v6.35.0+ which includes support for API version 2025-11-10.

Official Guide: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/2025-11-10

2. Next.js v6 Async auth() (Oct 2024) - BREAKING CHANGE ⚠️

Affects: All Next.js Server Components using auth()

// ❌ OLD (v5 - synchronous)
const { userId } = auth()

// ✅ NEW (v6 - asynchronous)
const { userId } = await auth()

Also affects: auth.protect() is now async in middleware

// ❌ OLD (v5)
auth.protect()

// ✅ NEW (v6)
await auth.protect()

Compatibility: Next.js 15, 16 supported. Static rendering by default.

3. PKCE Support for Custom OAuth (Nov 12, 2025)

Custom OIDC providers and social connections now support PKCE (Proof Key for Code Exchange) for enhanced security in native/mobile applications where client secrets cannot be safely stored.

Use case: Mobile apps, native apps, public clients that can't securely store secrets.

4. Client Trust: Credential Stuffing Defense (Nov 14, 2025)

Automatic secondary authentication when users sign in from unrecognized devices:

• Activates for users with valid passwords but no 2FA
• No configuration required
• Included in all Clerk plans

How it works: Clerk automatically prompts for additional verification (email code, backup code) when detecting sign-in from new device.

5. Next.js 16 Support (Nov 2025)

@clerk/nextjs v6.35.2+ includes cache invalidation improvements for Next.js 16 during sign-out.

Critical Patterns & Error Prevention

Next.js v6: Async auth() Helper

Pattern:

import { auth } from '@clerk/nextjs/server'

export default async function Page() {
  const { userId } = await auth()  // ← Must await

  if (!userId) {
    return <div>Unauthorized</div>
  }

  return <div>User ID: {userId}</div>
}

Cloudflare Workers: authorizedParties (CSRF Prevention)

CRITICAL: Always set authorizedParties to prevent CSRF attacks

import { verifyToken } from '@clerk/backend'

const { data, error } = await verifyToken(token, {
  secretKey: c.env.CLERK_SECRET_KEY,
  // REQUIRED: Prevent CSRF attacks
  authorizedParties: ['https://yourdomain.com'],
})

Why: Without authorizedParties, attackers can use valid tokens from other domains.

Source: https://clerk.com/docs/reference/backend/verify-token

clerkMiddleware() Configuration

Route Protection Patterns

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

// Define protected routes
const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/api/private(.*)',
])

const isAdminRoute = createRouteMatcher(['/admin(.*)'])

export default clerkMiddleware(async (auth, req) => {
  // Protect routes
  if (isProtectedRoute(req)) {
    await auth.protect()  // Redirects unauthenticated users
  }

  // Require specific permissions
  if (isAdminRoute(req)) {
    await auth.protect({
      role: 'org:admin',  // Requires organization admin role
    })
  }
})

All Middleware Options

Organization Sync (URL-based Org Activation)

⚠️ Next.js Only: This feature currently only works with clerkMiddleware() in Next.js. It does NOT work with authenticateRequest() in other runtimes (Cloudflare Workers, Express, etc.) due to Sec-Fetch-Dest header checks.

Source: GitHub Issue #7178

clerkMiddleware({
  organizationSyncOptions: {
    organizationPatterns: ['/orgs/:slug', '/orgs/:slug/(.*)'],
    personalAccountPatterns: ['/personal', '/personal/(.*)'],
  },
})

Webhooks

Webhook Verification

import { Webhook } from 'svix'

export async function POST(req: Request) {
  const payload = await req.text()
  const headers = {
    'svix-id': req.headers.get('svix-id')!,
    'svix-timestamp': req.headers.get('svix-timestamp')!,
    'svix-signature': req.headers.get('svix-signature')!,
  }

  const wh = new Webhook(process.env.CLERK_WEBHOOK_SIGNING_SECRET!)

  try {
    const event = wh.verify(payload, headers)
    // Process event
    return Response.json({ success: true })
  } catch (err) {
    return Response.json({ error: 'Invalid signature' }, { status: 400 })
  }
}

Common Event Types

⚠️ Important: Webhook routes must be PUBLIC (no auth). Add to middleware exclude list:

const isPublicRoute = createRouteMatcher([
  '/api/webhooks/clerk(.*)',  // Clerk webhooks are public
])

clerkMiddleware((auth, req) => {
  if (!isPublicRoute(req)) {
    auth.protect()
  }
})

UI Components Quick Reference

React Hooks

JWT Templates - Size Limits & Shortcodes

JWT Size Limitation: 1.2KB for Custom Claims ⚠️

Problem: Browser cookies limited to 4KB. Clerk's default claims consume ~2.8KB, leaving 1.2KB for custom claims.

⚠️ Development Note: When testing custom JWT claims in Vite dev mode, you may encounter "431 Request Header Fields Too Large" error. This is caused by Clerk's handshake token in the URL exceeding Vite's 8KB limit. See Issue #11 for solution.

Solution:

// ✅ GOOD: Minimal claims
{
  "user_id": "{{user.id}}",
  "email": "{{user.primary_email_address}}",
  "role": "{{user.public_metadata.role}}"
}

// ❌ BAD: Exceeds limit
{
  "bio": "{{user.public_metadata.bio}}",  // 6KB field
  "all_metadata": "{{user.public_metadata}}"  // Entire object
}

Best Practice: Store large data in database, include only identifiers/roles in JWT.

Available Shortcodes Reference

Advanced Features:

• String Interpolation: "{{user.last_name}} {{user.first_name}}"
• Conditional Fallbacks: "{{user.public_metadata.role || 'user'}}"
• Nested Metadata: "{{user.public_metadata.profile.interests}}"

Official Docs: https://clerk.com/docs/guides/sessions/jwt-templates

Testing with Clerk

Test Credentials (Fixed OTP: 424242)

Test Emails (no emails sent, fixed OTP):

john+clerk_test@example.com
jane+clerk_test@gmail.com

Test Phone Numbers (no SMS sent, fixed OTP):

+12015550100
+19735550133

Fixed OTP Code: 424242 (works for all test credentials)

Generate Session Tokens (60-second lifetime)

Script (scripts/generate-session-token.js):

# Generate token
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js

# Create new test user
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js --create-user

# Auto-refresh token every 50 seconds
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js --refresh

Manual Flow:

1. Create user: POST /v1/users
2. Create session: POST /v1/sessions
3. Generate token: POST /v1/sessions/{session_id}/tokens
4. Use in header: Authorization: Bearer <token>

E2E Testing with Playwright

Install @clerk/testing for automatic Testing Token management:

npm install -D @clerk/testing

Global Setup (global.setup.ts):

import { clerkSetup } from '@clerk/testing/playwright'
import { test as setup } from '@playwright/test'

setup('global setup', async ({}) => {
  await clerkSetup()
})

Test File (auth.spec.ts):

import { setupClerkTestingToken } from '@clerk/testing/playwright'
import { test } from '@playwright/test'

test('sign up', async ({ page }) => {
  await setupClerkTestingToken({ page })

  await page.goto('/sign-up')
  await page.fill('input[name="emailAddress"]', 'test+clerk_test@example.com')
  await page.fill('input[name="password"]', 'TestPassword123!')
  await page.click('button[type="submit"]')

  // Verify with fixed OTP
  await page.fill('input[name="code"]', '424242')
  await page.click('button[type="submit"]')

  await expect(page).toHaveURL('/dashboard')
})

Official Docs: https://clerk.com/docs/guides/development/testing/overview

Known Issues Prevention

This skill prevents 15 documented issues:

Issue #1: Missing Clerk Secret Key

Error: "Missing Clerk Secret Key or API Key" Source: https://stackoverflow.com/questions/77620604 Prevention: Always set in .env.local or via wrangler secret put

Issue #2: API Key → Secret Key Migration

Error: "apiKey is deprecated, use secretKey" Source: https://clerk.com/docs/upgrade-guides/core-2/backend Prevention: Replace apiKey with secretKey in all calls

Issue #3: JWKS Cache Race Condition

Error: "No JWK available" Source: https://github.com/clerk/javascript/blob/main/packages/backend/CHANGELOG.md Prevention: Use @clerk/backend@2.17.2 or later (fixed)

Issue #4: Missing authorizedParties (CSRF)

Error: No error, but CSRF vulnerability Source: https://clerk.com/docs/reference/backend/verify-token Prevention: Always set authorizedParties: ['https://yourdomain.com']

Issue #5: Import Path Changes (Core 2)

Error: "Cannot find module" Source: https://clerk.com/docs/upgrade-guides/core-2/backend Prevention: Update import paths for Core 2