Clerk auth with API version 2025-11-10 breaking changes (billing endpoints, payment_source→payment_method), Next.js v6 async auth(), PKCE for custom OAuth, credential stuffing defense...
Package Versions: @clerk/nextjs@6.35.4, @clerk/backend@2.23.2, @clerk/clerk-react@5.56.2, @clerk/testing@1.13.18 Breaking Changes: Nov 2025 - API version 2025-11-10, Oct 2024 - Next.js v6 async auth() Last Updated: 2025-11-22
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_amountRemoved Endpoints:
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
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.
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.
Automatic secondary authentication when users sign in from unrecognized devices:
How it works: Clerk automatically prompts for additional verification (email code, backup code) when detecting sign-in from new device.
@clerk/nextjs v6.35.2+ includes cache invalidation improvements for Next.js 16 during sign-out.
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>
}
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
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.
| Category | Shortcodes | Example |
|---|---|---|
| User ID & Name | {{user.id}}, {{user.first_name}}, {{user.last_name}}, {{user.full_name}} |
"John Doe" |
| Contact | {{user.primary_email_address}}, {{user.primary_phone_address}} |
"john@example.com" |
| Profile | {{user.image_url}}, {{user.username}}, {{user.created_at}} |
"https://..." |
| Verification | {{user.email_verified}}, {{user.phone_number_verified}} |
true |
| Metadata | {{user.public_metadata}}, {{user.public_metadata.FIELD}} |
{"role": "admin"} |
| Organization | org_id, org_slug, org_role (in sessionClaims) |
"org:admin" |
Advanced Features:
"{{user.last_name}} {{user.first_name}}""{{user.public_metadata.role || 'user'}}""{{user.public_metadata.profile.interests}}"Official Docs: https://clerk.com/docs/guides/sessions/jwt-templates
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)
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:
POST /v1/usersPOST /v1/sessionsPOST /v1/sessions/{session_id}/tokensAuthorization: Bearer <token>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
This skill prevents 11 documented issues:
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
Error: "apiKey is deprecated, use secretKey"
Source: https://clerk.com/docs/upgrade-guides/core-2/backend
Prevention: Replace apiKey with secretKey in all calls
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)
Error: No error, but CSRF vulnerability
Source: https://clerk.com/docs/reference/backend/verify-token
Prevention: Always set authorizedParties: ['https://yourdomain.com']
Error: "Cannot find module" Source: https://clerk.com/docs/upgrade-guides/core-2/backend Prevention: Update import paths for Core 2
Error: Token exceeds size limit Source: https://clerk.com/docs/backend-requests/making/custom-session-token Prevention: Keep custom claims under 1.2KB
Error: "API version v1 is deprecated" Source: https://clerk.com/docs/upgrade-guides/core-2/backend Prevention: Use latest SDK versions (API v2025-11-10)
Error: "cannot be used as a JSX component" Source: https://stackoverflow.com/questions/79265537 Prevention: Ensure React 19 compatibility with @clerk/clerk-react@5.56.2+
Error: "auth() is not a function"
Source: https://clerk.com/changelog/2024-10-22-clerk-nextjs-v6
Prevention: Always await: const { userId } = await auth()
Error: "Missing Publishable Key" or secret leaked
Prevention: Use correct prefixes (NEXT_PUBLIC_, VITE_), never commit secrets
Error: "431 Request Header Fields Too Large" when signing in
Source: Common in Vite dev mode when testing custom JWT claims
Cause: Clerk's __clerk_handshake token in URL exceeds Vite's 8KB header limit
Prevention:
Add to package.json:
{
"scripts": {
"dev": "NODE_OPTIONS='--max-http-header-size=32768' vite"
}
}
Temporary Workaround: Clear browser cache, sign out, sign back in
Why: Clerk dev tokens are larger than production; custom JWT claims increase handshake token size
Note: This is different from Issue #6 (session token size). Issue #6 is about cookies (1.2KB), this is about URL parameters in dev mode (8KB → 32KB).
/clerk/clerk-docsLatest (Nov 22, 2025):
{
"dependencies": {
"@clerk/nextjs": "^6.35.4",
"@clerk/clerk-react": "^5.56.2",
"@clerk/backend": "^2.23.2",
"@clerk/testing": "^1.13.18"
}
}
Token Efficiency:
Errors prevented: 11 documented issues with exact solutions Key value: API 2025-11-10 breaking changes, Next.js v6 async auth(), PKCE for custom OAuth, credential stuffing defense, JWT size limits, 431 header error workaround
Last verified: 2025-11-22 | Skill version: 2.0.0 | Changes: Added API version 2025-11-10 breaking changes (billing endpoints), PKCE support, Client Trust defense, Next.js 16 support. Removed tutorials (~480 lines). Updated SDK versions. Focused on breaking changes + error prevention + critical patterns.
