clerk-auth

SKILL.md

Clerk authentication with API keys, Next.js 16 middleware, and 15 documented error prevention patterns.

Supports user and organization-scoped API keys (beta, Dec 2025) with zero-code UI component and backend verification via verifyToken()

Next.js 16 requires proxy.ts instead of middleware.ts due to March 2025 security vulnerability; minimum version @clerk/nextjs@6.35.0+

API version 2025-11-10 introduces breaking changes: /commerce/ endpoints renamed to /billing/, payment_source → payment_method, removed fields in plan responses

Prevents 15 documented issues including JWKS cache race conditions, CSRF vulnerabilities (via authorizedParties), JWT size limits (1.2KB custom claims), async auth() helper confusion, and user type mismatches between client/server

Includes webhook verification patterns, clerkMiddleware route protection options, JWT template shortcodes, test credentials (OTP: 424242), and production guidance for GCP outage resilience

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'