Clerk Auth - Breaking Changes & Error Prevention Guide
Package Versions: @clerk/[email protected], @clerk/[email protected], @clerk/[email protected], @clerk/[email protected]
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.
import { APIKeys } from '@clerk/nextjs'
export default function SettingsPage() {
return (
<div>
<h2>API Keys</h2>
<APIKeys /> {}
</div>
)
}
Backend Verification:
import { verifyToken } from '@clerk/backend'
const { data, error } = await verifyToken(apiKey, {
secretKey: process.env.CLERK_SECRET_KEY,
authorizedParties: ['https://yourdomain.com'],
})
if (data?.tokenType === 'api_key') {
}
clerkMiddleware Token Types:
clerkMiddleware((auth, req) => {
const { userId, tokenType } = auth()
if (tokenType === 'api_key') {
} else if (tokenType === 'session_token') {
}
})
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:
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/[email protected]+ 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'
await clerkClient.users.updateUser(userId, {
passwordDigest: 'compromised',
})
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
{ payment_source_id: "...", payment_source: {...} }
{ 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()
const { userId } = auth()
const { userId } = await auth()
Also affects: auth.protect() is now async in middleware
auth.protect()
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()
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,
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'
const isProtectedRoute = createRouteMatcher([
'/dashboard(.*)',
'/api/private(.*)',
])
const isAdminRoute = createRouteMatcher(['/admin(.*)'])
export default clerkMiddleware(async (auth, req)
