[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6PY21M60JV0T2TPXMPM0ZCB":3,"skill-same:01M6PY21M60JV0T2TPXMPM0ZCB":182},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":25,"publishedAt":46,"linkOnly":47,"markdownContent":48,"markdownBody":49,"frontMatter":50,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":6,"ownerHtmlUrl":58,"ownerBlogUrl":6,"ownerDescription":59,"updatedAt":60,"install":61,"resources":73},"01M6PY21M60JV0T2TPXMPM0ZCB","clerk-auth",null,"Clerk auth with API Keys beta (Dec 2025), Next.js 16 proxy.ts (March 2025 CVE context), API version 2025-11-10 breaking changes, clerkMiddleware() options, webhooks, production considerations (GCP outages), and component reference. Prevents 15 documented errors. Use when: API keys for users\u002Forgs, Next.js 16 middleware filename, troubleshooting JWKS\u002FCSRF\u002FJWT\u002Ftoken-type-mismatch errors, webhook verification, user type inconsistencies, or testing with 424242 OTP.","Kernel8901\u002Fai-agent-skills-classification","Kernel8901","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F72647553?v=4","01M6KV388J2H5PNC8D8P940BJD","01M6KV38CS5B3AY63RKZB410YM",7,"MIT","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000010","后端与接口",[26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"auth","clerk auth","clerk","reference","api version","api keys","changes","for","keys","users","type","webhook","testing","version","use","context","Next.js","csrf","gcp","component","2026-11-10 10:12:30",false,"---\nname: clerk-auth\ndescription: |\n  Clerk auth with API Keys beta (Dec 2025), Next.js 16 proxy.ts (March 2025 CVE context), API version 2025-11-10 breaking changes, clerkMiddleware() options, webhooks, production considerations (GCP outages), and component reference. Prevents 15 documented errors. Use when: API keys for users\u002Forgs, Next.js 16 middleware filename, troubleshooting JWKS\u002FCSRF\u002FJWT\u002Ftoken-type-mismatch errors, webhook verification, user type inconsistencies, or testing with 424242 OTP.\nuser-invocable: true\n---\n\n# Clerk Auth - Breaking Changes & Error Prevention Guide\n\n**Package Versions**: @clerk\u002Fnextjs@6.36.7, @clerk\u002Fbackend@2.29.2, @clerk\u002Fclerk-react@5.59.2, @clerk\u002Ftesting@1.13.26\n**Breaking Changes**: Nov 2025 - API version 2025-11-10, Oct 2024 - Next.js v6 async auth()\n**Last Updated**: 2026-01-09\n\n---\n\n## What's New (Dec 2025 - Jan 2026)\n\n### 1. API Keys Beta (Dec 11, 2025) - NEW ✨\n\nUser-scoped and organization-scoped API keys for your application. Zero-code UI component.\n\n```typescript\n\u002F\u002F 1. Add the component for self-service API key management\nimport { APIKeys } from '@clerk\u002Fnextjs'\n\nexport default function SettingsPage() {\n  return (\n    \u003Cdiv>\n      \u003Ch2>API Keys\u003C\u002Fh2>\n      \u003CAPIKeys \u002F>  {\u002F* Full CRUD UI for user's API keys *\u002F}\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n**Backend Verification:**\n```typescript\nimport { verifyToken } from '@clerk\u002Fbackend'\n\n\u002F\u002F API keys are verified like session tokens\nconst { data, error } = await verifyToken(apiKey, {\n  secretKey: process.env.CLERK_SECRET_KEY,\n  authorizedParties: ['https:\u002F\u002Fyourdomain.com'],\n})\n\n\u002F\u002F Check token type\nif (data?.tokenType === 'api_key') {\n  \u002F\u002F Handle API key auth\n}\n```\n\n**clerkMiddleware Token Types:**\n```typescript\n\u002F\u002F v6.36.0+: Middleware can distinguish token types\nclerkMiddleware((auth, req) => {\n  const { userId, tokenType } = auth()\n\n  if (tokenType === 'api_key') {\n    \u002F\u002F API key auth - programmatic access\n  } else if (tokenType === 'session_token') {\n    \u002F\u002F Regular session - web UI access\n  }\n})\n```\n\n**Pricing (Beta = Free):**\n- Creation: $0.001\u002Fkey\n- Verification: $0.0001\u002Fverification\n\n### 2. Next.js 16: proxy.ts Middleware Filename (Dec 2025)\n\n**⚠️ BREAKING**: Next.js 16 changed middleware filename due to critical security vulnerability (CVE disclosed March 2025).\n\n**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).\n\n**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.\n\n```\nNext.js 15 and earlier: middleware.ts\nNext.js 16+:            proxy.ts\n```\n\n**Correct Setup for Next.js 16:**\n```typescript\n\u002F\u002F src\u002Fproxy.ts (NOT middleware.ts!)\nimport { clerkMiddleware } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default clerkMiddleware()\n\nexport const config = {\n  matcher: [\n    '\u002F((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',\n    '\u002F(api|trpc)(.*)',\n  ],\n}\n```\n\n**Minimum Version**: @clerk\u002Fnextjs@6.35.0+ required for Next.js 16 (fixes Turbopack build errors and cache invalidation on sign-out).\n\n### 3. Force Password Reset (Dec 19, 2025)\n\nAdministrators can mark passwords as compromised and force reset:\n\n```typescript\nimport { clerkClient } from '@clerk\u002Fbackend'\n\n\u002F\u002F Force password reset for a user\nawait clerkClient.users.updateUser(userId, {\n  passwordDigest: 'compromised',  \u002F\u002F Triggers reset on next sign-in\n})\n```\n\n### 4. Organization Reports & Filters (Dec 15-17, 2025)\n\nDashboard now includes org creation metrics and filtering by name\u002Fslug\u002Fdate.\n\n---\n\n## API Version 2025-11-10 Breaking Changes\n\n### 1. API Version 2025-11-10 (Nov 10, 2025) - BREAKING CHANGES ⚠️\n\n**Affects:** Applications using Clerk Billing\u002FCommerce APIs\n\n**Critical Changes:**\n- **Endpoint URLs:** `\u002Fcommerce\u002F` → `\u002Fbilling\u002F` (30+ endpoints)\n  ```\n  GET \u002Fv1\u002Fcommerce\u002Fplans → GET \u002Fv1\u002Fbilling\u002Fplans\n  GET \u002Fv1\u002Fcommerce\u002Fstatements → GET \u002Fv1\u002Fbilling\u002Fstatements\n  POST \u002Fv1\u002Fme\u002Fcommerce\u002Fcheckouts → POST \u002Fv1\u002Fme\u002Fbilling\u002Fcheckouts\n  ```\n\n- **Field Terminology:** `payment_source` → `payment_method`\n  ```typescript\n  \u002F\u002F OLD (deprecated)\n  { payment_source_id: \"...\", payment_source: {...} }\n\n  \u002F\u002F NEW (required)\n  { payment_method_id: \"...\", payment_method: {...} }\n  ```\n\n- **Removed Fields:** Plans responses no longer include:\n  - `amount`, `amount_formatted` (use `fee.amount` instead)\n  - `currency`, `currency_symbol` (use fee objects)\n  - `payer_type` (use `for_payer_type`)\n  - `annual_monthly_amount`, `annual_amount`\n\n- **Removed Endpoints:**\n  - Invoices endpoint (use statements)\n  - Products endpoint\n\n- **Null Handling:** Explicit rules - `null` means \"doesn't exist\", omitted means \"not asserting existence\"\n\n**Migration:** Update SDK to v6.35.0+ which includes support for API version 2025-11-10.\n\n**Official Guide:** https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fupgrading\u002Fupgrade-guides\u002F2025-11-10\n\n### 2. Next.js v6 Async auth() (Oct 2024) - BREAKING CHANGE ⚠️\n\n**Affects:** All Next.js Server Components using `auth()`\n\n```typescript\n\u002F\u002F ❌ OLD (v5 - synchronous)\nconst { userId } = auth()\n\n\u002F\u002F ✅ NEW (v6 - asynchronous)\nconst { userId } = await auth()\n```\n\n**Also affects:** `auth.protect()` is now async in middleware\n\n```typescript\n\u002F\u002F ❌ OLD (v5)\nauth.protect()\n\n\u002F\u002F ✅ NEW (v6)\nawait auth.protect()\n```\n\n**Compatibility:** Next.js 15, 16 supported. Static rendering by default.\n\n### 3. PKCE Support for Custom OAuth (Nov 12, 2025)\n\nCustom OIDC providers and social connections now support PKCE (Proof Key for Code Exchange) for enhanced security in native\u002Fmobile applications where client secrets cannot be safely stored.\n\n**Use case:** Mobile apps, native apps, public clients that can't securely store secrets.\n\n### 4. Client Trust: Credential Stuffing Defense (Nov 14, 2025)\n\nAutomatic secondary authentication when users sign in from unrecognized devices:\n- Activates for users with valid passwords but no 2FA\n- No configuration required\n- Included in all Clerk plans\n\n**How it works:** Clerk automatically prompts for additional verification (email code, backup code) when detecting sign-in from new device.\n\n### 5. Next.js 16 Support (Nov 2025)\n\n**@clerk\u002Fnextjs v6.35.2+** includes cache invalidation improvements for Next.js 16 during sign-out.\n\n---\n\n## Critical Patterns & Error Prevention\n\n### Next.js v6: Async auth() Helper\n\n**Pattern:**\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function Page() {\n  const { userId } = await auth()  \u002F\u002F ← Must await\n\n  if (!userId) {\n    return \u003Cdiv>Unauthorized\u003C\u002Fdiv>\n  }\n\n  return \u003Cdiv>User ID: {userId}\u003C\u002Fdiv>\n}\n```\n\n### Cloudflare Workers: authorizedParties (CSRF Prevention)\n\n**CRITICAL:** Always set `authorizedParties` to prevent CSRF attacks\n\n```typescript\nimport { verifyToken } from '@clerk\u002Fbackend'\n\nconst { data, error } = await verifyToken(token, {\n  secretKey: c.env.CLERK_SECRET_KEY,\n  \u002F\u002F REQUIRED: Prevent CSRF attacks\n  authorizedParties: ['https:\u002F\u002Fyourdomain.com'],\n})\n```\n\n**Why:** Without `authorizedParties`, attackers can use valid tokens from other domains.\n\n**Source:** https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n\n---\n\n## clerkMiddleware() Configuration\n\n### Route Protection Patterns\n\n```typescript\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\n\u002F\u002F Define protected routes\nconst isProtectedRoute = createRouteMatcher([\n  '\u002Fdashboard(.*)',\n  '\u002Fapi\u002Fprivate(.*)',\n])\n\nconst isAdminRoute = createRouteMatcher(['\u002Fadmin(.*)'])\n\nexport default clerkMiddleware(async (auth, req) => {\n  \u002F\u002F Protect routes\n  if (isProtectedRoute(req)) {\n    await auth.protect()  \u002F\u002F Redirects unauthenticated users\n  }\n\n  \u002F\u002F Require specific permissions\n  if (isAdminRoute(req)) {\n    await auth.protect({\n      role: 'org:admin',  \u002F\u002F Requires organization admin role\n    })\n  }\n})\n```\n\n### All Middleware Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `debug` | `boolean` | Enable debug logging |\n| `jwtKey` | `string` | JWKS public key for networkless verification |\n| `clockSkewInMs` | `number` | Token time variance (default: 5000ms) |\n| `organizationSyncOptions` | `object` | URL-based org activation |\n| `signInUrl` | `string` | Custom sign-in URL |\n| `signUpUrl` | `string` | Custom sign-up URL |\n\n### Organization Sync (URL-based Org Activation)\n\n**⚠️ 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.\n\n**Source**: [GitHub Issue #7178](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F7178)\n\n```typescript\nclerkMiddleware({\n  organizationSyncOptions: {\n    organizationPatterns: ['\u002Forgs\u002F:slug', '\u002Forgs\u002F:slug\u002F(.*)'],\n    personalAccountPatterns: ['\u002Fpersonal', '\u002Fpersonal\u002F(.*)'],\n  },\n})\n```\n\n---\n\n## Webhooks\n\n### Webhook Verification\n\n```typescript\nimport { Webhook } from 'svix'\n\nexport async function POST(req: Request) {\n  const payload = await req.text()\n  const headers = {\n    'svix-id': req.headers.get('svix-id')!,\n    'svix-timestamp': req.headers.get('svix-timestamp')!,\n    'svix-signature': req.headers.get('svix-signature')!,\n  }\n\n  const wh = new Webhook(process.env.CLERK_WEBHOOK_SIGNING_SECRET!)\n\n  try {\n    const event = wh.verify(payload, headers)\n    \u002F\u002F Process event\n    return Response.json({ success: true })\n  } catch (err) {\n    return Response.json({ error: 'Invalid signature' }, { status: 400 })\n  }\n}\n```\n\n### Common Event Types\n\n| Event | Trigger |\n|-------|---------|\n| `user.created` | New user signs up |\n| `user.updated` | User profile changes |\n| `user.deleted` | User account deleted |\n| `session.created` | New sign-in |\n| `session.ended` | Sign-out |\n| `organization.created` | New org created |\n| `organization.membership.created` | User joins org |\n\n**⚠️ Important:** Webhook routes must be PUBLIC (no auth). Add to middleware exclude list:\n\n```typescript\nconst isPublicRoute = createRouteMatcher([\n  '\u002Fapi\u002Fwebhooks\u002Fclerk(.*)',  \u002F\u002F Clerk webhooks are public\n])\n\nclerkMiddleware((auth, req) => {\n  if (!isPublicRoute(req)) {\n    auth.protect()\n  }\n})\n```\n\n---\n\n## UI Components Quick Reference\n\n| Component | Purpose |\n|-----------|---------|\n| `\u003CSignIn \u002F>` | Full sign-in flow |\n| `\u003CSignUp \u002F>` | Full sign-up flow |\n| `\u003CSignInButton \u002F>` | Trigger sign-in modal |\n| `\u003CSignUpButton \u002F>` | Trigger sign-up modal |\n| `\u003CSignedIn>` | Render only when authenticated |\n| `\u003CSignedOut>` | Render only when unauthenticated |\n| `\u003CUserButton \u002F>` | User menu with sign-out |\n| `\u003CUserProfile \u002F>` | Full profile management |\n| `\u003COrganizationSwitcher \u002F>` | Switch between orgs |\n| `\u003COrganizationProfile \u002F>` | Org settings |\n| `\u003CCreateOrganization \u002F>` | Create new org |\n| `\u003CAPIKeys \u002F>` | API key management (NEW) |\n\n### React Hooks\n\n| Hook | Returns |\n|------|---------|\n| `useAuth()` | `{ userId, sessionId, isLoaded, isSignedIn, getToken }` |\n| `useUser()` | `{ user, isLoaded, isSignedIn }` |\n| `useClerk()` | Clerk instance with methods |\n| `useSession()` | Current session object |\n| `useOrganization()` | Current org context |\n| `useOrganizationList()` | All user's orgs |\n\n---\n\n## JWT Templates - Size Limits & Shortcodes\n\n### JWT Size Limitation: 1.2KB for Custom Claims ⚠️\n\n**Problem**: Browser cookies limited to 4KB. Clerk's default claims consume ~2.8KB, leaving **1.2KB for custom claims**.\n\n**⚠️ 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](#issue-11-431-request-header-fields-too-large-vite-dev-mode) for solution.\n\n**Solution:**\n```json\n\u002F\u002F ✅ GOOD: Minimal claims\n{\n  \"user_id\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role}}\"\n}\n\n\u002F\u002F ❌ BAD: Exceeds limit\n{\n  \"bio\": \"{{user.public_metadata.bio}}\",  \u002F\u002F 6KB field\n  \"all_metadata\": \"{{user.public_metadata}}\"  \u002F\u002F Entire object\n}\n```\n\n**Best Practice**: Store large data in database, include only identifiers\u002Froles in JWT.\n\n### Available Shortcodes Reference\n\n| Category | Shortcodes | Example |\n|----------|-----------|---------|\n| **User ID & Name** | `{{user.id}}`, `{{user.first_name}}`, `{{user.last_name}}`, `{{user.full_name}}` | `\"John Doe\"` |\n| **Contact** | `{{user.primary_email_address}}`, `{{user.primary_phone_address}}` | `\"john@example.com\"` |\n| **Profile** | `{{user.image_url}}`, `{{user.username}}`, `{{user.created_at}}` | `\"https:\u002F\u002F...\"` |\n| **Verification** | `{{user.email_verified}}`, `{{user.phone_number_verified}}` | `true` |\n| **Metadata** | `{{user.public_metadata}}`, `{{user.public_metadata.FIELD}}` | `{\"role\": \"admin\"}` |\n| **Organization** | `org_id`, `org_slug`, `org_role` (in sessionClaims) | `\"org:admin\"` |\n\n**Advanced Features:**\n- **String Interpolation**: `\"{{user.last_name}} {{user.first_name}}\"`\n- **Conditional Fallbacks**: `\"{{user.public_metadata.role || 'user'}}\"`\n- **Nested Metadata**: `\"{{user.public_metadata.profile.interests}}\"`\n\n**Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n\n---\n\n## Testing with Clerk\n\n### Test Credentials (Fixed OTP: 424242)\n\n**Test Emails** (no emails sent, fixed OTP):\n```\njohn+clerk_test@example.com\njane+clerk_test@gmail.com\n```\n\n**Test Phone Numbers** (no SMS sent, fixed OTP):\n```\n+12015550100\n+19735550133\n```\n\n**Fixed OTP Code**: `424242` (works for all test credentials)\n\n### Generate Session Tokens (60-second lifetime)\n\n**Script** (`scripts\u002Fgenerate-session-token.js`):\n```bash\n# Generate token\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js\n\n# Create new test user\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --create-user\n\n# Auto-refresh token every 50 seconds\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --refresh\n```\n\n**Manual Flow**:\n1. Create user: `POST \u002Fv1\u002Fusers`\n2. Create session: `POST \u002Fv1\u002Fsessions`\n3. Generate token: `POST \u002Fv1\u002Fsessions\u002F{session_id}\u002Ftokens`\n4. Use in header: `Authorization: Bearer \u003Ctoken>`\n\n### E2E Testing with Playwright\n\nInstall `@clerk\u002Ftesting` for automatic Testing Token management:\n\n```bash\nnpm install -D @clerk\u002Ftesting\n```\n\n**Global Setup** (`global.setup.ts`):\n```typescript\nimport { clerkSetup } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test as setup } from '@playwright\u002Ftest'\n\nsetup('global setup', async ({}) => {\n  await clerkSetup()\n})\n```\n\n**Test File** (`auth.spec.ts`):\n```typescript\nimport { setupClerkTestingToken } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test } from '@playwright\u002Ftest'\n\ntest('sign up', async ({ page }) => {\n  await setupClerkTestingToken({ page })\n\n  await page.goto('\u002Fsign-up')\n  await page.fill('input[name=\"emailAddress\"]', 'test+clerk_test@example.com')\n  await page.fill('input[name=\"password\"]', 'TestPassword123!')\n  await page.click('button[type=\"submit\"]')\n\n  \u002F\u002F Verify with fixed OTP\n  await page.fill('input[name=\"code\"]', '424242')\n  await page.click('button[type=\"submit\"]')\n\n  await expect(page).toHaveURL('\u002Fdashboard')\n})\n```\n\n**Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Ftesting\u002Foverview\n\n---\n\n## Known Issues Prevention\n\nThis skill prevents **15 documented issues**:\n\n### Issue #1: Missing Clerk Secret Key\n**Error**: \"Missing Clerk Secret Key or API Key\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F77620604\n**Prevention**: Always set in `.env.local` or via `wrangler secret put`\n\n### Issue #2: API Key → Secret Key Migration\n**Error**: \"apiKey is deprecated, use secretKey\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Replace `apiKey` with `secretKey` in all calls\n\n### Issue #3: JWKS Cache Race Condition\n**Error**: \"No JWK available\"\n**Source**: https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fblob\u002Fmain\u002Fpackages\u002Fbackend\u002FCHANGELOG.md\n**Prevention**: Use @clerk\u002Fbackend@2.17.2 or later (fixed)\n\n### Issue #4: Missing authorizedParties (CSRF)\n**Error**: No error, but CSRF vulnerability\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n**Prevention**: Always set `authorizedParties: ['https:\u002F\u002Fyourdomain.com']`\n\n### Issue #5: Import Path Changes (Core 2)\n**Error**: \"Cannot find module\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Update import paths for Core 2\n\n### Issue #6: JWT Size Limit Exceeded\n**Error**: Token exceeds size limit\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fbackend-requests\u002Fmaking\u002Fcustom-session-token\n**Prevention**: Keep custom claims under 1.2KB\n\n### Issue #7: Deprecated API Version v1\n**Error**: \"API version v1 is deprecated\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Use latest SDK versions (API v2025-11-10)\n\n### Issue #8: ClerkProvider JSX Component Error\n**Error**: \"cannot be used as a JSX component\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F79265537\n**Prevention**: Ensure React 19 compatibility with @clerk\u002Fclerk-react@5.59.2+\n\n### Issue #9: Async auth() Helper Confusion\n**Error**: \"auth() is not a function\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fchangelog\u002F2024-10-22-clerk-nextjs-v6\n**Prevention**: Always await: `const { userId } = await auth()`\n\n### Issue #10: Environment Variable Misconfiguration\n**Error**: \"Missing Publishable Key\" or secret leaked\n**Prevention**: Use correct prefixes (`NEXT_PUBLIC_`, `VITE_`), never commit secrets\n\n### Issue #11: 431 Request Header Fields Too Large (Vite Dev Mode)\n**Error**: \"431 Request Header Fields Too Large\" when signing in\n**Source**: Common in Vite dev mode when testing custom JWT claims\n**Cause**: Clerk's `__clerk_handshake` token in URL exceeds Vite's 8KB header limit\n**Prevention**:\n\nAdd to `package.json`:\n```json\n{\n  \"scripts\": {\n    \"dev\": \"NODE_OPTIONS='--max-http-header-size=32768' vite\"\n  }\n}\n```\n\n**Temporary Workaround**: Clear browser cache, sign out, sign back in\n\n**Why**: Clerk dev tokens are larger than production; custom JWT claims increase handshake token size\n\n**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).\n\n### Issue #12: User Type Mismatch (useUser vs currentUser)\n**Error**: TypeScript errors when sharing user utilities across client\u002Fserver\n**Source**: [GitHub Issue #2176](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F2176)\n**Why It Happens**: `useUser()` returns `UserResource` (client-side) with different properties than `currentUser()` returns `User` (server-side). Client has `fullName`, `primaryEmailAddress` object; server has `primaryEmailAddressId` and `privateMetadata` instead.\n**Prevention**: Use shared properties only, or create separate utility functions for client vs server contexts.\n\n```typescript\n\u002F\u002F ✅ CORRECT: Use properties that exist in both\nconst primaryEmailAddress = user.emailAddresses.find(\n  ({ id }) => id === user.primaryEmailAddressId\n)\n\n\u002F\u002F ✅ CORRECT: Separate types\ntype ClientUser = ReturnType\u003Ctypeof useUser>['user']\ntype ServerUser = Awaited\u003CReturnType\u003Ctypeof currentUser>>\n```\n\n### Issue #13: Multiple acceptsToken Types Causes token-type-mismatch\n**Error**: \"token-type-mismatch\" when using `authenticateRequest()` with multiple token types\n**Source**: [GitHub Issue #7520](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F7520)\n**Why It Happens**: When using `authenticateRequest()` with multiple `acceptsToken` values (e.g., `['session_token', 'api_key']`), Clerk incorrectly throws token-type-mismatch error.\n**Prevention**: Upgrade to @clerk\u002Fbackend@2.29.2+ (fix available in snapshot, releasing soon).\n\n```typescript\n\u002F\u002F This now works in @clerk\u002Fbackend@2.29.2+\nconst result = await authenticateRequest(request, {\n  acceptsToken: ['session_token', 'api_key'],  \u002F\u002F Fixed!\n})\n```\n\n### Issue #14: deriveUrlFromHeaders Server Crash on Malformed URLs\n**Error**: Server crashes with URL parsing error\n**Source**: [GitHub Issue #7275](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F7275)\n**Why It Happens**: Internal `deriveUrlFromHeaders()` function performs unsafe URL parsing and crashes the entire server when receiving malformed URLs in headers (e.g., `x-forwarded-host: 'example.com[invalid]'`). This is a denial-of-service vulnerability.\n**Prevention**: Upgrade to @clerk\u002Fbackend@2.29.0+ (fixed).\n\n### Issue #15: treatPendingAsSignedOut Option for Pending Sessions\n**Error**: None - optional parameter for edge case handling\n**Source**: [Changelog @clerk\u002Fnextjs@6.32.0](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fblob\u002Fmain\u002Fpackages\u002Fnextjs\u002FCHANGELOG.md#6320)\n**Why It Exists**: Sessions can have a `pending` status during certain flows (e.g., credential stuffing defense secondary auth). By default, pending sessions are treated as signed-out (user is null).\n**Usage**: Set `treatPendingAsSignedOut: false` to treat pending as signed-in (available in @clerk\u002Fnextjs@6.32.0+).\n\n```typescript\n\u002F\u002F Default: pending = signed out\nconst user = await currentUser()  \u002F\u002F null if status is 'pending'\n\n\u002F\u002F Treat pending as signed in\nconst user = await currentUser({ treatPendingAsSignedOut: false })  \u002F\u002F defined if pending\n```\n\n---\n\n## Production Considerations\n\n### Service Availability & Reliability\n\n**Context**: Clerk experienced 3 major service disruptions in May-June 2025 attributed to Google Cloud Platform (GCP) outages. The June 26, 2025 outage lasted 45 minutes (6:16-7:01 UTC) and affected all Clerk customers.\n\n**Source**: [Clerk Postmortem: June 26, 2025](https:\u002F\u002Fclerk.com\u002Fblog\u002Fpostmortem-jun-26-2025-service-outage)\n\n**Mitigation Strategies**:\n- Monitor [Clerk Status](https:\u002F\u002Fstatus.clerk.com) for real-time updates\n- Implement graceful degradation when Clerk API is unavailable\n- Cache auth tokens locally where possible\n- For existing sessions, use `jwtKey` option for networkless verification:\n\n```typescript\nclerkMiddleware({\n  jwtKey: process.env.CLERK_JWT_KEY,  \u002F\u002F Allows offline token verification\n})\n```\n\n**Note**: During total outage, no new sessions can be created (auth requires Clerk API). However, existing sessions can continue working if you verify JWTs locally with `jwtKey`. Clerk committed to exploring multi-cloud redundancy to reduce single-vendor dependency risk.\n\n---\n\n## Official Documentation\n\n- **Clerk Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\n- **Next.js Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Fnextjs\u002Foverview\n- **React Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Foverview\n- **Backend SDK**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Foverview\n- **JWT Templates**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n- **API Version 2025-11-10 Upgrade**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fupgrading\u002Fupgrade-guides\u002F2025-11-10\n- **Testing Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Ftesting\u002Foverview\n- **Context7 Library ID**: `\u002Fclerk\u002Fclerk-docs`\n\n---\n\n## Package Versions\n\n**Latest (Nov 22, 2025):**\n```json\n{\n  \"dependencies\": {\n    \"@clerk\u002Fnextjs\": \"^6.36.7\",\n    \"@clerk\u002Fclerk-react\": \"^5.59.2\",\n    \"@clerk\u002Fbackend\": \"^2.29.2\",\n    \"@clerk\u002Ftesting\": \"^1.13.26\"\n  }\n}\n```\n\n---\n\n**Token Efficiency**:\n- **Without skill**: ~6,500 tokens (setup tutorials, JWT templates, testing setup, webhooks, production considerations)\n- **With skill**: ~3,200 tokens (breaking changes + critical patterns + error prevention + production guidance)\n- **Savings**: ~51% (~3,300 tokens)\n\n**Errors prevented**: 15 documented issues with exact solutions\n**Key value**: API Keys beta, Next.js 16 proxy.ts (with March 2025 CVE context), clerkMiddleware() options, webhooks, component reference, API 2025-11-10 breaking changes, JWT size limits, user type mismatches, production considerations (GCP outages, jwtKey offline verification)\n\n---\n\n**Last verified**: 2026-01-20 | **Skill version**: 3.1.0 | **Changes**: Added 4 new Known Issues (#12-15: user type mismatch, acceptsToken type mismatch, deriveUrlFromHeaders crash, treatPendingAsSignedOut option), expanded proxy.ts section with March 2025 CVE security context, added Production Considerations section (GCP outages + mitigation), added organizationSyncOptions Next.js-only limitation note, updated minimum version requirements for Next.js 16 (6.35.0+).\n","# Clerk Auth - Breaking Changes & Error Prevention Guide\n\n**Package Versions**: @clerk\u002Fnextjs@6.36.7, @clerk\u002Fbackend@2.29.2, @clerk\u002Fclerk-react@5.59.2, @clerk\u002Ftesting@1.13.26\n**Breaking Changes**: Nov 2025 - API version 2025-11-10, Oct 2024 - Next.js v6 async auth()\n**Last Updated**: 2026-01-09\n\n---\n\n## What's New (Dec 2025 - Jan 2026)\n\n### 1. API Keys Beta (Dec 11, 2025) - NEW ✨\n\nUser-scoped and organization-scoped API keys for your application. Zero-code UI component.\n\n```typescript\n\u002F\u002F 1. Add the component for self-service API key management\nimport { APIKeys } from '@clerk\u002Fnextjs'\n\nexport default function SettingsPage() {\n  return (\n    \u003Cdiv>\n      \u003Ch2>API Keys\u003C\u002Fh2>\n      \u003CAPIKeys \u002F>  {\u002F* Full CRUD UI for user's API keys *\u002F}\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n**Backend Verification:**\n```typescript\nimport { verifyToken } from '@clerk\u002Fbackend'\n\n\u002F\u002F API keys are verified like session tokens\nconst { data, error } = await verifyToken(apiKey, {\n  secretKey: process.env.CLERK_SECRET_KEY,\n  authorizedParties: ['https:\u002F\u002Fyourdomain.com'],\n})\n\n\u002F\u002F Check token type\nif (data?.tokenType === 'api_key') {\n  \u002F\u002F Handle API key auth\n}\n```\n\n**clerkMiddleware Token Types:**\n```typescript\n\u002F\u002F v6.36.0+: Middleware can distinguish token types\nclerkMiddleware((auth, req) => {\n  const { userId, tokenType } = auth()\n\n  if (tokenType === 'api_key') {\n    \u002F\u002F API key auth - programmatic access\n  } else if (tokenType === 'session_token') {\n    \u002F\u002F Regular session - web UI access\n  }\n})\n```\n\n**Pricing (Beta = Free):**\n- Creation: $0.001\u002Fkey\n- Verification: $0.0001\u002Fverification\n\n### 2. Next.js 16: proxy.ts Middleware Filename (Dec 2025)\n\n**⚠️ BREAKING**: Next.js 16 changed middleware filename due to critical security vulnerability (CVE disclosed March 2025).\n\n**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).\n\n**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.\n\n```\nNext.js 15 and earlier: middleware.ts\nNext.js 16+:            proxy.ts\n```\n\n**Correct Setup for Next.js 16:**\n```typescript\n\u002F\u002F src\u002Fproxy.ts (NOT middleware.ts!)\nimport { clerkMiddleware } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default clerkMiddleware()\n\nexport const config = {\n  matcher: [\n    '\u002F((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',\n    '\u002F(api|trpc)(.*)',\n  ],\n}\n```\n\n**Minimum Version**: @clerk\u002Fnextjs@6.35.0+ required for Next.js 16 (fixes Turbopack build errors and cache invalidation on sign-out).\n\n### 3. Force Password Reset (Dec 19, 2025)\n\nAdministrators can mark passwords as compromised and force reset:\n\n```typescript\nimport { clerkClient } from '@clerk\u002Fbackend'\n\n\u002F\u002F Force password reset for a user\nawait clerkClient.users.updateUser(userId, {\n  passwordDigest: 'compromised',  \u002F\u002F Triggers reset on next sign-in\n})\n```\n\n### 4. Organization Reports & Filters (Dec 15-17, 2025)\n\nDashboard now includes org creation metrics and filtering by name\u002Fslug\u002Fdate.\n\n---\n\n## API Version 2025-11-10 Breaking Changes\n\n### 1. API Version 2025-11-10 (Nov 10, 2025) - BREAKING CHANGES ⚠️\n\n**Affects:** Applications using Clerk Billing\u002FCommerce APIs\n\n**Critical Changes:**\n- **Endpoint URLs:** `\u002Fcommerce\u002F` → `\u002Fbilling\u002F` (30+ endpoints)\n  ```\n  GET \u002Fv1\u002Fcommerce\u002Fplans → GET \u002Fv1\u002Fbilling\u002Fplans\n  GET \u002Fv1\u002Fcommerce\u002Fstatements → GET \u002Fv1\u002Fbilling\u002Fstatements\n  POST \u002Fv1\u002Fme\u002Fcommerce\u002Fcheckouts → POST \u002Fv1\u002Fme\u002Fbilling\u002Fcheckouts\n  ```\n\n- **Field Terminology:** `payment_source` → `payment_method`\n  ```typescript\n  \u002F\u002F OLD (deprecated)\n  { payment_source_id: \"...\", payment_source: {...} }\n\n  \u002F\u002F NEW (required)\n  { payment_method_id: \"...\", payment_method: {...} }\n  ```\n\n- **Removed Fields:** Plans responses no longer include:\n  - `amount`, `amount_formatted` (use `fee.amount` instead)\n  - `currency`, `currency_symbol` (use fee objects)\n  - `payer_type` (use `for_payer_type`)\n  - `annual_monthly_amount`, `annual_amount`\n\n- **Removed Endpoints:**\n  - Invoices endpoint (use statements)\n  - Products endpoint\n\n- **Null Handling:** Explicit rules - `null` means \"doesn't exist\", omitted means \"not asserting existence\"\n\n**Migration:** Update SDK to v6.35.0+ which includes support for API version 2025-11-10.\n\n**Official Guide:** https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fupgrading\u002Fupgrade-guides\u002F2025-11-10\n\n### 2. Next.js v6 Async auth() (Oct 2024) - BREAKING CHANGE ⚠️\n\n**Affects:** All Next.js Server Components using `auth()`\n\n```typescript\n\u002F\u002F ❌ OLD (v5 - synchronous)\nconst { userId } = auth()\n\n\u002F\u002F ✅ NEW (v6 - asynchronous)\nconst { userId } = await auth()\n```\n\n**Also affects:** `auth.protect()` is now async in middleware\n\n```typescript\n\u002F\u002F ❌ OLD (v5)\nauth.protect()\n\n\u002F\u002F ✅ NEW (v6)\nawait auth.protect()\n```\n\n**Compatibility:** Next.js 15, 16 supported. Static rendering by default.\n\n### 3. PKCE Support for Custom OAuth (Nov 12, 2025)\n\nCustom OIDC providers and social connections now support PKCE (Proof Key for Code Exchange) for enhanced security in native\u002Fmobile applications where client secrets cannot be safely stored.\n\n**Use case:** Mobile apps, native apps, public clients that can't securely store secrets.\n\n### 4. Client Trust: Credential Stuffing Defense (Nov 14, 2025)\n\nAutomatic secondary authentication when users sign in from unrecognized devices:\n- Activates for users with valid passwords but no 2FA\n- No configuration required\n- Included in all Clerk plans\n\n**How it works:** Clerk automatically prompts for additional verification (email code, backup code) when detecting sign-in from new device.\n\n### 5. Next.js 16 Support (Nov 2025)\n\n**@clerk\u002Fnextjs v6.35.2+** includes cache invalidation improvements for Next.js 16 during sign-out.\n\n---\n\n## Critical Patterns & Error Prevention\n\n### Next.js v6: Async auth() Helper\n\n**Pattern:**\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function Page() {\n  const { userId } = await auth()  \u002F\u002F ← Must await\n\n  if (!userId) {\n    return \u003Cdiv>Unauthorized\u003C\u002Fdiv>\n  }\n\n  return \u003Cdiv>User ID: {userId}\u003C\u002Fdiv>\n}\n```\n\n### Cloudflare Workers: authorizedParties (CSRF Prevention)\n\n**CRITICAL:** Always set `authorizedParties` to prevent CSRF attacks\n\n```typescript\nimport { verifyToken } from '@clerk\u002Fbackend'\n\nconst { data, error } = await verifyToken(token, {\n  secretKey: c.env.CLERK_SECRET_KEY,\n  \u002F\u002F REQUIRED: Prevent CSRF attacks\n  authorizedParties: ['https:\u002F\u002Fyourdomain.com'],\n})\n```\n\n**Why:** Without `authorizedParties`, attackers can use valid tokens from other domains.\n\n**Source:** https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n\n---\n\n## clerkMiddleware() Configuration\n\n### Route Protection Patterns\n\n```typescript\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\n\u002F\u002F Define protected routes\nconst isProtectedRoute = createRouteMatcher([\n  '\u002Fdashboard(.*)',\n  '\u002Fapi\u002Fprivate(.*)',\n])\n\nconst isAdminRoute = createRouteMatcher(['\u002Fadmin(.*)'])\n\nexport default clerkMiddleware(async (auth, req) => {\n  \u002F\u002F Protect routes\n  if (isProtectedRoute(req)) {\n    await auth.protect()  \u002F\u002F Redirects unauthenticated users\n  }\n\n  \u002F\u002F Require specific permissions\n  if (isAdminRoute(req)) {\n    await auth.protect({\n      role: 'org:admin',  \u002F\u002F Requires organization admin role\n    })\n  }\n})\n```\n\n### All Middleware Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `debug` | `boolean` | Enable debug logging |\n| `jwtKey` | `string` | JWKS public key for networkless verification |\n| `clockSkewInMs` | `number` | Token time variance (default: 5000ms) |\n| `organizationSyncOptions` | `object` | URL-based org activation |\n| `signInUrl` | `string` | Custom sign-in URL |\n| `signUpUrl` | `string` | Custom sign-up URL |\n\n### Organization Sync (URL-based Org Activation)\n\n**⚠️ 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.\n\n**Source**: [GitHub Issue #7178](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F7178)\n\n```typescript\nclerkMiddleware({\n  organizationSyncOptions: {\n    organizationPatterns: ['\u002Forgs\u002F:slug', '\u002Forgs\u002F:slug\u002F(.*)'],\n    personalAccountPatterns: ['\u002Fpersonal', '\u002Fpersonal\u002F(.*)'],\n  },\n})\n```\n\n---\n\n## Webhooks\n\n### Webhook Verification\n\n```typescript\nimport { Webhook } from 'svix'\n\nexport async function POST(req: Request) {\n  const payload = await req.text()\n  const headers = {\n    'svix-id': req.headers.get('svix-id')!,\n    'svix-timestamp': req.headers.get('svix-timestamp')!,\n    'svix-signature': req.headers.get('svix-signature')!,\n  }\n\n  const wh = new Webhook(process.env.CLERK_WEBHOOK_SIGNING_SECRET!)\n\n  try {\n    const event = wh.verify(payload, headers)\n    \u002F\u002F Process event\n    return Response.json({ success: true })\n  } catch (err) {\n    return Response.json({ error: 'Invalid signature' }, { status: 400 })\n  }\n}\n```\n\n### Common Event Types\n\n| Event | Trigger |\n|-------|---------|\n| `user.created` | New user signs up |\n| `user.updated` | User profile changes |\n| `user.deleted` | User account deleted |\n| `session.created` | New sign-in |\n| `session.ended` | Sign-out |\n| `organization.created` | New org created |\n| `organization.membership.created` | User joins org |\n\n**⚠️ Important:** Webhook routes must be PUBLIC (no auth). Add to middleware exclude list:\n\n```typescript\nconst isPublicRoute = createRouteMatcher([\n  '\u002Fapi\u002Fwebhooks\u002Fclerk(.*)',  \u002F\u002F Clerk webhooks are public\n])\n\nclerkMiddleware((auth, req) => {\n  if (!isPublicRoute(req)) {\n    auth.protect()\n  }\n})\n```\n\n---\n\n## UI Components Quick Reference\n\n| Component | Purpose |\n|-----------|---------|\n| `\u003CSignIn \u002F>` | Full sign-in flow |\n| `\u003CSignUp \u002F>` | Full sign-up flow |\n| `\u003CSignInButton \u002F>` | Trigger sign-in modal |\n| `\u003CSignUpButton \u002F>` | Trigger sign-up modal |\n| `\u003CSignedIn>` | Render only when authenticated |\n| `\u003CSignedOut>` | Render only when unauthenticated |\n| `\u003CUserButton \u002F>` | User menu with sign-out |\n| `\u003CUserProfile \u002F>` | Full profile management |\n| `\u003COrganizationSwitcher \u002F>` | Switch between orgs |\n| `\u003COrganizationProfile \u002F>` | Org settings |\n| `\u003CCreateOrganization \u002F>` | Create new org |\n| `\u003CAPIKeys \u002F>` | API key management (NEW) |\n\n### React Hooks\n\n| Hook | Returns |\n|------|---------|\n| `useAuth()` | `{ userId, sessionId, isLoaded, isSignedIn, getToken }` |\n| `useUser()` | `{ user, isLoaded, isSignedIn }` |\n| `useClerk()` | Clerk instance with methods |\n| `useSession()` | Current session object |\n| `useOrganization()` | Current org context |\n| `useOrganizationList()` | All user's orgs |\n\n---\n\n## JWT Templates - Size Limits & Shortcodes\n\n### JWT Size Limitation: 1.2KB for Custom Claims ⚠️\n\n**Problem**: Browser cookies limited to 4KB. Clerk's default claims consume ~2.8KB, leaving **1.2KB for custom claims**.\n\n**⚠️ 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](#issue-11-431-request-header-fields-too-large-vite-dev-mode) for solution.\n\n**Solution:**\n```json\n\u002F\u002F ✅ GOOD: Minimal claims\n{\n  \"user_id\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role}}\"\n}\n\n\u002F\u002F ❌ BAD: Exceeds limit\n{\n  \"bio\": \"{{user.public_metadata.bio}}\",  \u002F\u002F 6KB field\n  \"all_metadata\": \"{{user.public_metadata}}\"  \u002F\u002F Entire object\n}\n```\n\n**Best Practice**: Store large data in database, include only identifiers\u002Froles in JWT.\n\n### Available Shortcodes Reference\n\n| Category | Shortcodes | Example |\n|----------|-----------|---------|\n| **User ID & Name** | `{{user.id}}`, `{{user.first_name}}`, `{{user.last_name}}`, `{{user.full_name}}` | `\"John Doe\"` |\n| **Contact** | `{{user.primary_email_address}}`, `{{user.primary_phone_address}}` | `\"john@example.com\"` |\n| **Profile** | `{{user.image_url}}`, `{{user.username}}`, `{{user.created_at}}` | `\"https:\u002F\u002F...\"` |\n| **Verification** | `{{user.email_verified}}`, `{{user.phone_number_verified}}` | `true` |\n| **Metadata** | `{{user.public_metadata}}`, `{{user.public_metadata.FIELD}}` | `{\"role\": \"admin\"}` |\n| **Organization** | `org_id`, `org_slug`, `org_role` (in sessionClaims) | `\"org:admin\"` |\n\n**Advanced Features:**\n- **String Interpolation**: `\"{{user.last_name}} {{user.first_name}}\"`\n- **Conditional Fallbacks**: `\"{{user.public_metadata.role || 'user'}}\"`\n- **Nested Metadata**: `\"{{user.public_metadata.profile.interests}}\"`\n\n**Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n\n---\n\n## Testing with Clerk\n\n### Test Credentials (Fixed OTP: 424242)\n\n**Test Emails** (no emails sent, fixed OTP):\n```\njohn+clerk_test@example.com\njane+clerk_test@gmail.com\n```\n\n**Test Phone Numbers** (no SMS sent, fixed OTP):\n```\n+12015550100\n+19735550133\n```\n\n**Fixed OTP Code**: `424242` (works for all test credentials)\n\n### Generate Session Tokens (60-second lifetime)\n\n**Script** (`scripts\u002Fgenerate-session-token.js`):\n```bash\n# Generate token\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js\n\n# Create new test user\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --create-user\n\n# Auto-refresh token every 50 seconds\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --refresh\n```\n\n**Manual Flow**:\n1. Create user: `POST \u002Fv1\u002Fusers`\n2. Create session: `POST \u002Fv1\u002Fsessions`\n3. Generate token: `POST \u002Fv1\u002Fsessions\u002F{session_id}\u002Ftokens`\n4. Use in header: `Authorization: Bearer \u003Ctoken>`\n\n### E2E Testing with Playwright\n\nInstall `@clerk\u002Ftesting` for automatic Testing Token management:\n\n```bash\nnpm install -D @clerk\u002Ftesting\n```\n\n**Global Setup** (`global.setup.ts`):\n```typescript\nimport { clerkSetup } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test as setup } from '@playwright\u002Ftest'\n\nsetup('global setup', async ({}) => {\n  await clerkSetup()\n})\n```\n\n**Test File** (`auth.spec.ts`):\n```typescript\nimport { setupClerkTestingToken } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test } from '@playwright\u002Ftest'\n\ntest('sign up', async ({ page }) => {\n  await setupClerkTestingToken({ page })\n\n  await page.goto('\u002Fsign-up')\n  await page.fill('input[name=\"emailAddress\"]', 'test+clerk_test@example.com')\n  await page.fill('input[name=\"password\"]', 'TestPassword123!')\n  await page.click('button[type=\"submit\"]')\n\n  \u002F\u002F Verify with fixed OTP\n  await page.fill('input[name=\"code\"]', '424242')\n  await page.click('button[type=\"submit\"]')\n\n  await expect(page).toHaveURL('\u002Fdashboard')\n})\n```\n\n**Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Ftesting\u002Foverview\n\n---\n\n## Known Issues Prevention\n\nThis skill prevents **15 documented issues**:\n\n### Issue #1: Missing Clerk Secret Key\n**Error**: \"Missing Clerk Secret Key or API Key\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F77620604\n**Prevention**: Always set in `.env.local` or via `wrangler secret put`\n\n### Issue #2: API Key → Secret Key Migration\n**Error**: \"apiKey is deprecated, use secretKey\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Replace `apiKey` with `secretKey` in all calls\n\n### Issue #3: JWKS Cache Race Condition\n**Error**: \"No JWK available\"\n**Source**: https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fblob\u002Fmain\u002Fpackages\u002Fbackend\u002FCHANGELOG.md\n**Prevention**: Use @clerk\u002Fbackend@2.17.2 or later (fixed)\n\n### Issue #4: Missing authorizedParties (CSRF)\n**Error**: No error, but CSRF vulnerability\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n**Prevention**: Always set `authorizedParties: ['https:\u002F\u002Fyourdomain.com']`\n\n### Issue #5: Import Path Changes (Core 2)\n**Error**: \"Cannot find module\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Update import paths for Core 2\n\n### Issue #6: JWT Size Limit Exceeded\n**Error**: Token exceeds size limit\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fbackend-requests\u002Fmaking\u002Fcustom-session-token\n**Prevention**: Keep custom claims under 1.2KB\n\n### Issue #7: Deprecated API Version v1\n**Error**: \"API version v1 is deprecated\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Use latest SDK versions (API v2025-11-10)\n\n### Issue #8: ClerkProvider JSX Component Error\n**Error**: \"cannot be used as a JSX component\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F79265537\n**Prevention**: Ensure React 19 compatibility with @clerk\u002Fclerk-react@5.59.2+\n\n### Issue #9: Async auth() Helper Confusion\n**Error**: \"auth() is not a function\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fchangelog\u002F2024-10-22-clerk-nextjs-v6\n**Prevention**: Always await: `const { userId } = await auth()`\n\n### Issue #10: Environment Variable Misconfiguration\n**Error**: \"Missing Publishable Key\" or secret leaked\n**Prevention**: Use correct prefixes (`NEXT_PUBLIC_`, `VITE_`), never commit secrets\n\n### Issue #11: 431 Request Header Fields Too Large (Vite Dev Mode)\n**Error**: \"431 Request Header Fields Too Large\" when signing in\n**Source**: Common in Vite dev mode when testing custom JWT claims\n**Cause**: Clerk's `__clerk_handshake` token in URL exceeds Vite's 8KB header limit\n**Prevention**:\n\nAdd to `package.json`:\n```json\n{\n  \"scripts\": {\n    \"dev\": \"NODE_OPTIONS='--max-http-header-size=32768' vite\"\n  }\n}\n```\n\n**Temporary Workaround**: Clear browser cache, sign out, sign back in\n\n**Why**: Clerk dev tokens are larger than production; custom JWT claims increase handshake token size\n\n**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).\n\n### Issue #12: User Type Mismatch (useUser vs currentUser)\n**Error**: TypeScript errors when sharing user utilities across client\u002Fserver\n**Source**: [GitHub Issue #2176](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F2176)\n**Why It Happens**: `useUser()` returns `UserResource` (client-side) with different properties than `currentUser()` returns `User` (server-side). Client has `fullName`, `primaryEmailAddress` object; server has `primaryEmailAddressId` and `privateMetadata` instead.\n**Prevention**: Use shared properties only, or create separate utility functions for client vs server contexts.\n\n```typescript\n\u002F\u002F ✅ CORRECT: Use properties that exist in both\nconst primaryEmailAddress = user.emailAddresses.find(\n  ({ id }) => id === user.primaryEmailAddressId\n)\n\n\u002F\u002F ✅ CORRECT: Separate types\ntype ClientUser = ReturnType\u003Ctypeof useUser>['user']\ntype ServerUser = Awaited\u003CReturnType\u003Ctypeof currentUser>>\n```\n\n### Issue #13: Multiple acceptsToken Types Causes token-type-mismatch\n**Error**: \"token-type-mismatch\" when using `authenticateRequest()` with multiple token types\n**Source**: [GitHub Issue #7520](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F7520)\n**Why It Happens**: When using `authenticateRequest()` with multiple `acceptsToken` values (e.g., `['session_token', 'api_key']`), Clerk incorrectly throws token-type-mismatch error.\n**Prevention**: Upgrade to @clerk\u002Fbackend@2.29.2+ (fix available in snapshot, releasing soon).\n\n```typescript\n\u002F\u002F This now works in @clerk\u002Fbackend@2.29.2+\nconst result = await authenticateRequest(request, {\n  acceptsToken: ['session_token', 'api_key'],  \u002F\u002F Fixed!\n})\n```\n\n### Issue #14: deriveUrlFromHeaders Server Crash on Malformed URLs\n**Error**: Server crashes with URL parsing error\n**Source**: [GitHub Issue #7275](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fissues\u002F7275)\n**Why It Happens**: Internal `deriveUrlFromHeaders()` function performs unsafe URL parsing and crashes the entire server when receiving malformed URLs in headers (e.g., `x-forwarded-host: 'example.com[invalid]'`). This is a denial-of-service vulnerability.\n**Prevention**: Upgrade to @clerk\u002Fbackend@2.29.0+ (fixed).\n\n### Issue #15: treatPendingAsSignedOut Option for Pending Sessions\n**Error**: None - optional parameter for edge case handling\n**Source**: [Changelog @clerk\u002Fnextjs@6.32.0](https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fblob\u002Fmain\u002Fpackages\u002Fnextjs\u002FCHANGELOG.md#6320)\n**Why It Exists**: Sessions can have a `pending` status during certain flows (e.g., credential stuffing defense secondary auth). By default, pending sessions are treated as signed-out (user is null).\n**Usage**: Set `treatPendingAsSignedOut: false` to treat pending as signed-in (available in @clerk\u002Fnextjs@6.32.0+).\n\n```typescript\n\u002F\u002F Default: pending = signed out\nconst user = await currentUser()  \u002F\u002F null if status is 'pending'\n\n\u002F\u002F Treat pending as signed in\nconst user = await currentUser({ treatPendingAsSignedOut: false })  \u002F\u002F defined if pending\n```\n\n---\n\n## Production Considerations\n\n### Service Availability & Reliability\n\n**Context**: Clerk experienced 3 major service disruptions in May-June 2025 attributed to Google Cloud Platform (GCP) outages. The June 26, 2025 outage lasted 45 minutes (6:16-7:01 UTC) and affected all Clerk customers.\n\n**Source**: [Clerk Postmortem: June 26, 2025](https:\u002F\u002Fclerk.com\u002Fblog\u002Fpostmortem-jun-26-2025-service-outage)\n\n**Mitigation Strategies**:\n- Monitor [Clerk Status](https:\u002F\u002Fstatus.clerk.com) for real-time updates\n- Implement graceful degradation when Clerk API is unavailable\n- Cache auth tokens locally where possible\n- For existing sessions, use `jwtKey` option for networkless verification:\n\n```typescript\nclerkMiddleware({\n  jwtKey: process.env.CLERK_JWT_KEY,  \u002F\u002F Allows offline token verification\n})\n```\n\n**Note**: During total outage, no new sessions can be created (auth requires Clerk API). However, existing sessions can continue working if you verify JWTs locally with `jwtKey`. Clerk committed to exploring multi-cloud redundancy to reduce single-vendor dependency risk.\n\n---\n\n## Official Documentation\n\n- **Clerk Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\n- **Next.js Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Fnextjs\u002Foverview\n- **React Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Foverview\n- **Backend SDK**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Foverview\n- **JWT Templates**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n- **API Version 2025-11-10 Upgrade**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fupgrading\u002Fupgrade-guides\u002F2025-11-10\n- **Testing Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Ftesting\u002Foverview\n- **Context7 Library ID**: `\u002Fclerk\u002Fclerk-docs`\n\n---\n\n## Package Versions\n\n**Latest (Nov 22, 2025):**\n```json\n{\n  \"dependencies\": {\n    \"@clerk\u002Fnextjs\": \"^6.36.7\",\n    \"@clerk\u002Fclerk-react\": \"^5.59.2\",\n    \"@clerk\u002Fbackend\": \"^2.29.2\",\n    \"@clerk\u002Ftesting\": \"^1.13.26\"\n  }\n}\n```\n\n---\n\n**Token Efficiency**:\n- **Without skill**: ~6,500 tokens (setup tutorials, JWT templates, testing setup, webhooks, production considerations)\n- **With skill**: ~3,200 tokens (breaking changes + critical patterns + error prevention + production guidance)\n- **Savings**: ~51% (~3,300 tokens)\n\n**Errors prevented**: 15 documented issues with exact solutions\n**Key value**: API Keys beta, Next.js 16 proxy.ts (with March 2025 CVE context), clerkMiddleware() options, webhooks, component reference, API 2025-11-10 breaking changes, JWT size limits, user type mismatches, production considerations (GCP outages, jwtKey offline verification)\n\n---\n\n**Last verified**: 2026-01-20 | **Skill version**: 3.1.0 | **Changes**: Added 4 new Known Issues (#12-15: user type mismatch, acceptsToken type mismatch, deriveUrlFromHeaders crash, treatPendingAsSignedOut option), expanded proxy.ts section with March 2025 CVE security context, added Production Considerations section (GCP outages + mitigation), added organizationSyncOptions Next.js-only limitation note, updated minimum version requirements for Next.js 16 (6.35.0+).\n",{"name":5,"description":51,"user-invocable":52},"Clerk auth with API Keys beta (Dec 2025), Next.js 16 proxy.ts (March 2025 CVE context), API version 2025-11-10 breaking changes, clerkMiddleware() options, webhooks, production considerations (GCP outages), and component reference. Prevents 15 documented errors. Use when: API keys for users\u002Forgs, Next.js 16 middleware filename, troubleshooting JWKS\u002FCSRF\u002FJWT\u002Ftoken-type-mismatch errors, webhook verification, user type inconsistencies, or testing with 424242 OTP.\n",true,"main","f4cb2d49f7667e79ef7804f50396d5aaffdf1f56","安全与密码\u002Fclerk-auth",1,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification","https:\u002F\u002Fgithub.com\u002FKernel8901","a little little little dobe in life but science geek","2026-04-05 16:43:56",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":52},[63,66,69],{"tool":64,"command":65},"npx","npx skills add Kernel8901\u002Fai-agent-skills-classification --skill clerk-auth",{"tool":67,"command":68},"bunx","bunx skills add Kernel8901\u002Fai-agent-skills-classification --skill clerk-auth",{"tool":70,"command":71},"pnpm","pnpm dlx skills add Kernel8901\u002Fai-agent-skills-classification --skill clerk-auth","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002FSKILL.md",[74,80,84,88,94,98,102,106,110,114,118,122,128,132,136,140,144,148,152,158,162,166,170,174,178],{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"_meta.json","REFERENCE","参考文档",284,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002F_meta.json",{"path":81,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":82,"sourceHtmlUrl":83},".claude-plugin\u002Fplugin.json",740,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002F.claude-plugin\u002Fplugin.json",{"path":85,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":86,"sourceHtmlUrl":87},"agents\u002Fclerk-setup.md",5797,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Fagents\u002Fclerk-setup.md",{"path":89,"resourceType":90,"resourceTypeDesc":91,"sizeBytes":92,"sourceHtmlUrl":93},"assets\u002Fexample-template.txt","ASSET","资产文件",416,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Fassets\u002Fexample-template.txt",{"path":95,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":96,"sourceHtmlUrl":97},"commands\u002Fsetup.md",4219,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Fcommands\u002Fsetup.md",{"path":99,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":100,"sourceHtmlUrl":101},"README.md",5848,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002FREADME.md",{"path":103,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":104,"sourceHtmlUrl":105},"references\u002Fcommon-errors.md",15438,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Freferences\u002Fcommon-errors.md",{"path":107,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":108,"sourceHtmlUrl":109},"references\u002Fexample-reference.md",760,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Freferences\u002Fexample-reference.md",{"path":111,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":112,"sourceHtmlUrl":113},"references\u002Fjwt-claims-guide.md",17769,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Freferences\u002Fjwt-claims-guide.md",{"path":115,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":116,"sourceHtmlUrl":117},"references\u002Ftesting-guide.md",14045,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Freferences\u002Ftesting-guide.md",{"path":119,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":120,"sourceHtmlUrl":121},"rules\u002Fclerk-auth.md",3466,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Frules\u002Fclerk-auth.md",{"path":123,"resourceType":124,"resourceTypeDesc":125,"sizeBytes":126,"sourceHtmlUrl":127},"scripts\u002Fexample-script.sh","SCRIPT","脚本",302,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Fscripts\u002Fexample-script.sh",{"path":129,"resourceType":124,"resourceTypeDesc":125,"sizeBytes":130,"sourceHtmlUrl":131},"scripts\u002Fgenerate-session-token.js",6725,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Fscripts\u002Fgenerate-session-token.js",{"path":133,"resourceType":124,"resourceTypeDesc":125,"sizeBytes":134,"sourceHtmlUrl":135},"templates\u002Fcloudflare\u002Fworker-auth.ts",4534,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fcloudflare\u002Fworker-auth.ts",{"path":137,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":138,"sourceHtmlUrl":139},"templates\u002Fjwt\u002Fadvanced-template.json",1102,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fjwt\u002Fadvanced-template.json",{"path":141,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":142,"sourceHtmlUrl":143},"templates\u002Fjwt\u002Fbasic-template.json",411,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fjwt\u002Fbasic-template.json",{"path":145,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":146,"sourceHtmlUrl":147},"templates\u002Fjwt\u002Fgrafbase-template.json",744,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fjwt\u002Fgrafbase-template.json",{"path":149,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":150,"sourceHtmlUrl":151},"templates\u002Fjwt\u002Fsupabase-template.json",747,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fjwt\u002Fsupabase-template.json",{"path":153,"resourceType":154,"resourceTypeDesc":155,"sizeBytes":156,"sourceHtmlUrl":157},"templates\u002Fnextjs\u002Fapp-layout.tsx","OTHER","其他",1930,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fnextjs\u002Fapp-layout.tsx",{"path":159,"resourceType":124,"resourceTypeDesc":125,"sizeBytes":160,"sourceHtmlUrl":161},"templates\u002Fnextjs\u002Fmiddleware.ts",3734,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fnextjs\u002Fmiddleware.ts",{"path":163,"resourceType":154,"resourceTypeDesc":155,"sizeBytes":164,"sourceHtmlUrl":165},"templates\u002Fnextjs\u002Fserver-component-example.tsx",2643,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fnextjs\u002Fserver-component-example.tsx",{"path":167,"resourceType":154,"resourceTypeDesc":155,"sizeBytes":168,"sourceHtmlUrl":169},"templates\u002Freact\u002FApp.tsx",6124,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Freact\u002FApp.tsx",{"path":171,"resourceType":154,"resourceTypeDesc":155,"sizeBytes":172,"sourceHtmlUrl":173},"templates\u002Freact\u002Fmain.tsx",1517,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Freact\u002Fmain.tsx",{"path":175,"resourceType":124,"resourceTypeDesc":125,"sizeBytes":176,"sourceHtmlUrl":177},"templates\u002Ftypescript\u002Fcustom-jwt-types.d.ts",3025,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Ftypescript\u002Fcustom-jwt-types.d.ts",{"path":179,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":180,"sourceHtmlUrl":181},"templates\u002Fvite\u002Fpackage.json",1392,"https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F安全与密码\u002Fclerk-auth\u002Ftemplates\u002Fvite\u002Fpackage.json",[183,206,238,249,259,288],{"skillNo":184,"name":185,"nameZh":6,"description":186,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":187,"categories":188,"keywords":189,"publishedAt":46},"01M6Q5R6WZ06RRB9RQTW54B34B","zyfai","Earn yield on any Ethereum wallet on Base, Arbitrum, and Plasma. Use when a user wants passive DeFi yield on their funds. Deploys a non-custodial subaccount (Safe) linked to their EOA, enables automated yield optimization, and lets them deposit\u002Fwithdraw anytime.","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzyfai-sdk\u002FSKILL.md",[],[185,190,191,192,193,194,40,195,196,197,198,199,200,201,202,203,204,205],"safe","ethereum","defi","Optimization","user","Wallet","base","deposit","withdraw","yield","arbitrum","non-custodial","passive","defi yield","earn","yield optimization",{"skillNo":207,"name":208,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":209,"categories":210,"keywords":220,"publishedAt":46},"01M6Q5R337B5JSNER4P4YS03TN","zerion-api","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzerion-api\u002FSKILL.md",[211,212,215],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":213,"categoryName":214,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":216,"categoryName":217,"taxonomyType":218,"taxonomyTypeDesc":219},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[221,222,223,224,225,226,227,192,228,195,229,230,231,232,233,234,235,236,237],"api","zerion api","zerion","MCP","mcp server","server","blockchain","transactions","crypto wallet","crypto","evm","solana","query","across","positions","token","prices",{"skillNo":239,"name":240,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":241,"categories":242,"keywords":246,"publishedAt":46},"01M6Q5QZFYTDAZMZ27BN5VZXAR","zerion-api-skill","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzerion-api-skill\u002FSKILL.md",[243,244,245],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":213,"categoryName":214,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":216,"categoryName":217,"taxonomyType":218,"taxonomyTypeDesc":219},[221,247,248,222,223,224,225,226,227,192,228,195,230,231,232,233,234,235,236,237],"api skill","zerion api skill",{"skillNo":250,"name":251,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":252,"categories":253,"keywords":257,"publishedAt":46},"01M6Q5QW17QW98RA3FE45E4RD8","zerion-api-mcp","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fzerion-api-mcp\u002FSKILL.md",[254,255,256],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":213,"categoryName":214,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":216,"categoryName":217,"taxonomyType":218,"taxonomyTypeDesc":219},[224,221,258,222,223,225,226,192,228,195,229,230,231,232,233,234,235,236,237],"zerion api mcp",{"skillNo":260,"name":261,"nameZh":6,"description":262,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":263,"categories":264,"keywords":268,"publishedAt":46},"01M6Q5QQYZB7A501BDEQWKGSJT","yahoo-finance-forex","Fetches real-time FOREX news and market data from Yahoo Finance for major currency pairs (EUR\u002FUSD, GBP\u002FUSD, USD\u002FJPY, etc.). Analyzes sentiment and provides trading context.","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fyahoo-finance-forex\u002FSKILL.md",[265],{"categoryNo":266,"categoryName":267,"taxonomyType":218,"taxonomyTypeDesc":219},"01JBSEEDCAT000000000000040","财务",[269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,33],"finance","yahoo finance","forex","yahoo","yahoo finance forex","github","https","sentiment","real-time","python3","install","Market","usd","news","time","currency","gbp","pip","market data",{"skillNo":289,"name":290,"nameZh":6,"description":291,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":292,"categories":293,"keywords":295,"publishedAt":46},"01M6Q5QM6VS84WZVM7BKXXPF32","yahoo-finance","This skill should be used when the user asks to \"get stock prices\", \"check stock quotes\", \"look up earnings\", \"get financial data\", \"find trending stocks\", or needs stock market data from Yahoo Finance.","https:\u002F\u002Fgithub.com\u002FKernel8901\u002Fai-agent-skills-classification\u002Fblob\u002Fmain\u002F金融\u002Fyahoo-finance-cli\u002FSKILL.md",[294],{"categoryNo":266,"categoryName":267,"taxonomyType":218,"taxonomyTypeDesc":219},[269,270,272,296,297,298,299,300,301,280,302,303,304,305,306,307,308,309,237,287],"cli","homebrew","find","check","brew","up","local","get","stock","link","trending","sf","quotes","ln"]