[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6F8F19TYPJBJWWBGTW50HNJ":3,"skill-same:01M6F8F19TYPJBJWWBGTW50HNJ":83},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":49,"linkOnly":50,"markdownContent":51,"markdownBody":52,"frontMatter":53,"refName":60,"commitSha":61,"skillDirectory":62,"forksCount":63,"repositoryHtmlUrl":64,"repositoryHomepageUrl":65,"ownerHtmlUrl":66,"ownerBlogUrl":6,"ownerDescription":67,"updatedAt":68,"install":69,"resources":82},"01M6F8F19TYPJBJWWBGTW50HNJ","clerk-core-workflow-b",null,"Implement session management and middleware with Clerk.\nUse when managing user sessions, configuring route protection,\nor implementing token refresh and custom JWT templates.\nTrigger with phrases like \"clerk session\", \"clerk middleware\",\n\"clerk route protection\", \"clerk token\", \"clerk JWT\".","ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",66,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fjeremylongshore\u002Fclaude-code-plugins-plus-skills\u002Fclerk-core-workflow-b\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48],"workflow","core","clerk core workflow b","clerk","clerk-core","openclaw","session management","middleware","trigger","io","token","route","use","session","edit","write","read","saas","code","sessions","2026-11-10 10:12:30",false,"---\nname: clerk-core-workflow-b\ndescription: |\n  Implement session management and middleware with Clerk.\n  Use when managing user sessions, configuring route protection,\n  or implementing token refresh and custom JWT templates.\n  Trigger with phrases like \"clerk session\", \"clerk middleware\",\n  \"clerk route protection\", \"clerk token\", \"clerk JWT\".\nallowed-tools: Read, Write, Edit, Grep\nversion: 1.0.0\nlicense: MIT\nauthor: Jeremy Longshore \u003Cjeremy@intentsolutions.io>\ncompatible-with: claude-code, codex, openclaw\ntags: [saas, clerk, clerk-core, sessions, middleware]\n\n---\n# Clerk Core Workflow B: Session & Middleware\n\n## Overview\nImplement session management and route protection with Clerk middleware. Covers `clerkMiddleware()` configuration, `auth()` patterns, custom session claims, JWT templates for external services, organization-scoped sessions, and session token v2.\n\n## Prerequisites\n- `@clerk\u002Fnextjs` installed with ClerkProvider wrapping the app\n- Next.js 14+ with App Router\n- Sign-in\u002Fsign-up flows working (`clerk-core-workflow-a` completed)\n\n## Instructions\n\n### Step 1: Configure clerkMiddleware with Route Matchers\n```typescript\n\u002F\u002F middleware.ts (project root)\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\nconst isPublicRoute = createRouteMatcher([\n  '\u002F',\n  '\u002Fsign-in(.*)',\n  '\u002Fsign-up(.*)',\n  '\u002Fapi\u002Fwebhooks(.*)',\n  '\u002Fpricing',\n  '\u002Fblog(.*)',\n])\n\nconst isAdminRoute = createRouteMatcher(['\u002Fadmin(.*)'])\nconst isApiRoute = createRouteMatcher(['\u002Fapi(.*)'])\n\nexport default clerkMiddleware(async (auth, req) => {\n  \u002F\u002F Public routes: no auth required\n  if (isPublicRoute(req)) return\n\n  \u002F\u002F Admin routes: require org:admin role\n  if (isAdminRoute(req)) {\n    await auth.protect({ role: 'org:admin' })\n    return\n  }\n\n  \u002F\u002F All other routes: require authentication\n  await auth.protect()\n})\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**Key behavior:** `clerkMiddleware()` does NOT protect any routes by default. You must explicitly call `auth.protect()` for routes that require authentication. This is a design decision to avoid over-blocking.\n\n### Step 2: Protect API Routes with auth()\n```typescript\n\u002F\u002F app\u002Fapi\u002Fdata\u002Froute.ts\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport async function GET() {\n  const { userId, orgId, has } = await auth()\n\n  if (!userId) {\n    return Response.json({ error: 'Unauthorized' }, { status: 401 })\n  }\n\n  \u002F\u002F Permission-based authorization\n  if (!has({ permission: 'org:data:read' })) {\n    return Response.json({ error: 'Forbidden' }, { status: 403 })\n  }\n\n  const data = orgId\n    ? await db.items.findMany({ where: { organizationId: orgId } })\n    : await db.items.findMany({ where: { ownerId: userId } })\n\n  return Response.json({ data, userId, orgId })\n}\n\nexport async function POST(req: Request) {\n  const { userId, orgId, has } = await auth()\n  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })\n  if (!has({ permission: 'org:data:write' })) {\n    return Response.json({ error: 'Forbidden' }, { status: 403 })\n  }\n\n  const body = await req.json()\n  const item = await db.items.create({\n    data: { ...body, ownerId: userId, organizationId: orgId },\n  })\n  return Response.json({ item }, { status: 201 })\n}\n```\n\n### Step 3: Server Component Auth Patterns\n```typescript\n\u002F\u002F app\u002Fdashboard\u002Fpage.tsx\nimport { auth, currentUser } from '@clerk\u002Fnextjs\u002Fserver'\nimport { redirect } from 'next\u002Fnavigation'\n\nexport default async function DashboardPage() {\n  const { userId, orgId, orgRole, has, sessionClaims } = await auth()\n  if (!userId) redirect('\u002Fsign-in')\n\n  \u002F\u002F auth() is free (JWT parsing) — use for lightweight checks\n  const isAdmin = has({ role: 'org:admin' })\n\n  \u002F\u002F currentUser() costs a Backend API call — use only when you need full profile\n  const user = await currentUser()\n\n  return (\n    \u003Cdiv>\n      \u003Ch1>Welcome, {user?.firstName}\u003C\u002Fh1>\n      \u003Cp>Organization: {orgId || 'Personal account'}\u003C\u002Fp>\n      \u003Cp>Role: {orgRole || 'N\u002FA'}\u003C\u002Fp>\n      {isAdmin && \u003Ca href=\"\u002Fadmin\">Admin Panel\u003C\u002Fa>}\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n### Step 4: Custom Session Claims\nCustomize in **Dashboard > Sessions > Customize session token:**\n\n```json\n{\n  \"metadata\": \"{{user.public_metadata}}\",\n  \"email\": \"{{user.primary_email_address}}\"\n}\n```\n\nThen declare types and access in code:\n```typescript\n\u002F\u002F types\u002Fclerk.d.ts\ndeclare global {\n  interface CustomJwtSessionClaims {\n    metadata?: {\n      role?: string\n      plan?: string\n    }\n    email?: string\n  }\n}\nexport {}\n```\n\n```typescript\n\u002F\u002F Access custom claims (no API call needed — embedded in JWT)\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport async function GET() {\n  const { sessionClaims } = await auth()\n\n  const userPlan = sessionClaims?.metadata?.plan || 'free'\n  const userEmail = sessionClaims?.email\n\n  return Response.json({ plan: userPlan, email: userEmail })\n}\n```\n\n**Warning:** Session token cookie limit is 4KB. Custom claims should be under 1.2KB. Store large data in your database, not in session claims.\n\n### Step 5: JWT Templates for External Services\n```typescript\n\u002F\u002F app\u002Fapi\u002Fsupabase-data\u002Froute.ts\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\nimport { createClient } from '@supabase\u002Fsupabase-js'\n\nexport async function GET() {\n  const { userId, getToken } = await auth()\n  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })\n\n  \u002F\u002F Get a JWT with Supabase-compatible claims\n  \u002F\u002F Configure the template in Dashboard > JWT Templates\n  const supabaseToken = await getToken({ template: 'supabase' })\n\n  const supabase = createClient(\n    process.env.NEXT_PUBLIC_SUPABASE_URL!,\n    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,\n    { global: { headers: { Authorization: `Bearer ${supabaseToken}` } } }\n  )\n\n  const { data } = await supabase.from('items').select('*')\n  return Response.json({ data })\n}\n```\n\nConfigure JWT template in **Dashboard > JWT Templates > New template**:\n```json\n{\n  \"sub\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"authenticated\",\n  \"aud\": \"authenticated\"\n}\n```\n\n### Step 6: Organization-Scoped Sessions\n```typescript\n'use client'\nimport { useOrganizationList, useOrganization, useAuth } from '@clerk\u002Fnextjs'\n\nexport function OrgSwitcher() {\n  const { organizationList, setActive, isLoaded } = useOrganizationList({\n    userMemberships: { infinite: true },\n  })\n  const { organization } = useOrganization()\n\n  if (!isLoaded) return \u003Cdiv>Loading orgs...\u003C\u002Fdiv>\n\n  return (\n    \u003Cdiv>\n      \u003Cp>Active: {organization?.name || 'Personal account'}\u003C\u002Fp>\n      \u003Cul>\n        {organizationList?.map(({ organization: org, membership }) => (\n          \u003Cli key={org.id}>\n            \u003Cbutton onClick={() => setActive({ organization: org.id })}>\n              {org.name} ({membership.role})\n            \u003C\u002Fbutton>\n          \u003C\u002Fli>\n        ))}\n        \u003Cli>\n          \u003Cbutton onClick={() => setActive({ organization: null })}>\n            Personal account\n          \u003C\u002Fbutton>\n        \u003C\u002Fli>\n      \u003C\u002Ful>\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n### Step 7: Server Action Permission Guards\n```typescript\n'use server'\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport async function deleteItem(itemId: string) {\n  const { userId, orgId, has } = await auth()\n  if (!userId) throw new Error('Unauthorized')\n  if (!has({ permission: 'org:data:delete' })) {\n    throw new Error('You do not have permission to delete items')\n  }\n\n  await db.items.delete({ where: { id: itemId, organizationId: orgId } })\n  return { success: true }\n}\n\nexport async function updateOrgSettings(settings: Record\u003Cstring, any>) {\n  const { orgId, has } = await auth()\n  if (!orgId) throw new Error('No organization selected')\n  if (!has({ role: 'org:admin' })) {\n    throw new Error('Only admins can update organization settings')\n  }\n\n  await db.orgSettings.upsert({\n    where: { orgId },\n    update: settings,\n    create: { orgId, ...settings },\n  })\n  return { success: true }\n}\n```\n\n## Error Handling\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Middleware redirect loop | Sign-in page not in `isPublicRoute` | Add `\u002Fsign-in(.*)` to public route matcher |\n| 401 on API route | Token not forwarded | Include credentials in fetch or use server-side `auth()` |\n| `orgId` is null | No active organization | Prompt user with `\u003COrganizationSwitcher \u002F>` |\n| `has()` always false | Permission not assigned to role | Check Dashboard > Organizations > Roles |\n| Session expired | Token TTL exceeded | Clerk auto-refreshes; if stuck, clear cookies |\n| `auth() was called but clerkMiddleware() not detected` | Middleware missing or wrong location | Ensure `middleware.ts` at project root |\n\n## Enterprise Considerations\n- Session token v2 (default since April 2025) is more compact -- if your downstream services parse JWTs, verify they handle the new format\n- `auth.protect()` in middleware returns a 401\u002Fredirect before reaching your route handler -- this is more efficient than checking `userId` in every route\n- For permission-based access, prefer `has({ permission: '...' })` over `has({ role: '...' })` -- permissions decouple authorization from role names\n- JWT templates support custom `iss`, `aud`, and `exp` claims for integrating with Hasura, Supabase, Convex, Neon, and other services\n- Organization switching changes the active session scope instantly -- no page reload needed\n\n## Resources\n- [clerkMiddleware() Reference](https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fnextjs\u002Fclerk-middleware)\n- [auth() Reference](https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fnextjs\u002Fapp-router\u002Fauth)\n- [Custom Session Tokens](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fcustomize-session-tokens)\n- [JWT Templates](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates)\n\n## Next Steps\nProceed to `clerk-webhooks-events` for webhook and event handling.\n\n","# Clerk Core Workflow B: Session & Middleware\n\n## Overview\nImplement session management and route protection with Clerk middleware. Covers `clerkMiddleware()` configuration, `auth()` patterns, custom session claims, JWT templates for external services, organization-scoped sessions, and session token v2.\n\n## Prerequisites\n- `@clerk\u002Fnextjs` installed with ClerkProvider wrapping the app\n- Next.js 14+ with App Router\n- Sign-in\u002Fsign-up flows working (`clerk-core-workflow-a` completed)\n\n## Instructions\n\n### Step 1: Configure clerkMiddleware with Route Matchers\n```typescript\n\u002F\u002F middleware.ts (project root)\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\nconst isPublicRoute = createRouteMatcher([\n  '\u002F',\n  '\u002Fsign-in(.*)',\n  '\u002Fsign-up(.*)',\n  '\u002Fapi\u002Fwebhooks(.*)',\n  '\u002Fpricing',\n  '\u002Fblog(.*)',\n])\n\nconst isAdminRoute = createRouteMatcher(['\u002Fadmin(.*)'])\nconst isApiRoute = createRouteMatcher(['\u002Fapi(.*)'])\n\nexport default clerkMiddleware(async (auth, req) => {\n  \u002F\u002F Public routes: no auth required\n  if (isPublicRoute(req)) return\n\n  \u002F\u002F Admin routes: require org:admin role\n  if (isAdminRoute(req)) {\n    await auth.protect({ role: 'org:admin' })\n    return\n  }\n\n  \u002F\u002F All other routes: require authentication\n  await auth.protect()\n})\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**Key behavior:** `clerkMiddleware()` does NOT protect any routes by default. You must explicitly call `auth.protect()` for routes that require authentication. This is a design decision to avoid over-blocking.\n\n### Step 2: Protect API Routes with auth()\n```typescript\n\u002F\u002F app\u002Fapi\u002Fdata\u002Froute.ts\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport async function GET() {\n  const { userId, orgId, has } = await auth()\n\n  if (!userId) {\n    return Response.json({ error: 'Unauthorized' }, { status: 401 })\n  }\n\n  \u002F\u002F Permission-based authorization\n  if (!has({ permission: 'org:data:read' })) {\n    return Response.json({ error: 'Forbidden' }, { status: 403 })\n  }\n\n  const data = orgId\n    ? await db.items.findMany({ where: { organizationId: orgId } })\n    : await db.items.findMany({ where: { ownerId: userId } })\n\n  return Response.json({ data, userId, orgId })\n}\n\nexport async function POST(req: Request) {\n  const { userId, orgId, has } = await auth()\n  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })\n  if (!has({ permission: 'org:data:write' })) {\n    return Response.json({ error: 'Forbidden' }, { status: 403 })\n  }\n\n  const body = await req.json()\n  const item = await db.items.create({\n    data: { ...body, ownerId: userId, organizationId: orgId },\n  })\n  return Response.json({ item }, { status: 201 })\n}\n```\n\n### Step 3: Server Component Auth Patterns\n```typescript\n\u002F\u002F app\u002Fdashboard\u002Fpage.tsx\nimport { auth, currentUser } from '@clerk\u002Fnextjs\u002Fserver'\nimport { redirect } from 'next\u002Fnavigation'\n\nexport default async function DashboardPage() {\n  const { userId, orgId, orgRole, has, sessionClaims } = await auth()\n  if (!userId) redirect('\u002Fsign-in')\n\n  \u002F\u002F auth() is free (JWT parsing) — use for lightweight checks\n  const isAdmin = has({ role: 'org:admin' })\n\n  \u002F\u002F currentUser() costs a Backend API call — use only when you need full profile\n  const user = await currentUser()\n\n  return (\n    \u003Cdiv>\n      \u003Ch1>Welcome, {user?.firstName}\u003C\u002Fh1>\n      \u003Cp>Organization: {orgId || 'Personal account'}\u003C\u002Fp>\n      \u003Cp>Role: {orgRole || 'N\u002FA'}\u003C\u002Fp>\n      {isAdmin && \u003Ca href=\"\u002Fadmin\">Admin Panel\u003C\u002Fa>}\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n### Step 4: Custom Session Claims\nCustomize in **Dashboard > Sessions > Customize session token:**\n\n```json\n{\n  \"metadata\": \"{{user.public_metadata}}\",\n  \"email\": \"{{user.primary_email_address}}\"\n}\n```\n\nThen declare types and access in code:\n```typescript\n\u002F\u002F types\u002Fclerk.d.ts\ndeclare global {\n  interface CustomJwtSessionClaims {\n    metadata?: {\n      role?: string\n      plan?: string\n    }\n    email?: string\n  }\n}\nexport {}\n```\n\n```typescript\n\u002F\u002F Access custom claims (no API call needed — embedded in JWT)\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport async function GET() {\n  const { sessionClaims } = await auth()\n\n  const userPlan = sessionClaims?.metadata?.plan || 'free'\n  const userEmail = sessionClaims?.email\n\n  return Response.json({ plan: userPlan, email: userEmail })\n}\n```\n\n**Warning:** Session token cookie limit is 4KB. Custom claims should be under 1.2KB. Store large data in your database, not in session claims.\n\n### Step 5: JWT Templates for External Services\n```typescript\n\u002F\u002F app\u002Fapi\u002Fsupabase-data\u002Froute.ts\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\nimport { createClient } from '@supabase\u002Fsupabase-js'\n\nexport async function GET() {\n  const { userId, getToken } = await auth()\n  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })\n\n  \u002F\u002F Get a JWT with Supabase-compatible claims\n  \u002F\u002F Configure the template in Dashboard > JWT Templates\n  const supabaseToken = await getToken({ template: 'supabase' })\n\n  const supabase = createClient(\n    process.env.NEXT_PUBLIC_SUPABASE_URL!,\n    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,\n    { global: { headers: { Authorization: `Bearer ${supabaseToken}` } } }\n  )\n\n  const { data } = await supabase.from('items').select('*')\n  return Response.json({ data })\n}\n```\n\nConfigure JWT template in **Dashboard > JWT Templates > New template**:\n```json\n{\n  \"sub\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"authenticated\",\n  \"aud\": \"authenticated\"\n}\n```\n\n### Step 6: Organization-Scoped Sessions\n```typescript\n'use client'\nimport { useOrganizationList, useOrganization, useAuth } from '@clerk\u002Fnextjs'\n\nexport function OrgSwitcher() {\n  const { organizationList, setActive, isLoaded } = useOrganizationList({\n    userMemberships: { infinite: true },\n  })\n  const { organization } = useOrganization()\n\n  if (!isLoaded) return \u003Cdiv>Loading orgs...\u003C\u002Fdiv>\n\n  return (\n    \u003Cdiv>\n      \u003Cp>Active: {organization?.name || 'Personal account'}\u003C\u002Fp>\n      \u003Cul>\n        {organizationList?.map(({ organization: org, membership }) => (\n          \u003Cli key={org.id}>\n            \u003Cbutton onClick={() => setActive({ organization: org.id })}>\n              {org.name} ({membership.role})\n            \u003C\u002Fbutton>\n          \u003C\u002Fli>\n        ))}\n        \u003Cli>\n          \u003Cbutton onClick={() => setActive({ organization: null })}>\n            Personal account\n          \u003C\u002Fbutton>\n        \u003C\u002Fli>\n      \u003C\u002Ful>\n    \u003C\u002Fdiv>\n  )\n}\n```\n\n### Step 7: Server Action Permission Guards\n```typescript\n'use server'\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport async function deleteItem(itemId: string) {\n  const { userId, orgId, has } = await auth()\n  if (!userId) throw new Error('Unauthorized')\n  if (!has({ permission: 'org:data:delete' })) {\n    throw new Error('You do not have permission to delete items')\n  }\n\n  await db.items.delete({ where: { id: itemId, organizationId: orgId } })\n  return { success: true }\n}\n\nexport async function updateOrgSettings(settings: Record\u003Cstring, any>) {\n  const { orgId, has } = await auth()\n  if (!orgId) throw new Error('No organization selected')\n  if (!has({ role: 'org:admin' })) {\n    throw new Error('Only admins can update organization settings')\n  }\n\n  await db.orgSettings.upsert({\n    where: { orgId },\n    update: settings,\n    create: { orgId, ...settings },\n  })\n  return { success: true }\n}\n```\n\n## Error Handling\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Middleware redirect loop | Sign-in page not in `isPublicRoute` | Add `\u002Fsign-in(.*)` to public route matcher |\n| 401 on API route | Token not forwarded | Include credentials in fetch or use server-side `auth()` |\n| `orgId` is null | No active organization | Prompt user with `\u003COrganizationSwitcher \u002F>` |\n| `has()` always false | Permission not assigned to role | Check Dashboard > Organizations > Roles |\n| Session expired | Token TTL exceeded | Clerk auto-refreshes; if stuck, clear cookies |\n| `auth() was called but clerkMiddleware() not detected` | Middleware missing or wrong location | Ensure `middleware.ts` at project root |\n\n## Enterprise Considerations\n- Session token v2 (default since April 2025) is more compact -- if your downstream services parse JWTs, verify they handle the new format\n- `auth.protect()` in middleware returns a 401\u002Fredirect before reaching your route handler -- this is more efficient than checking `userId` in every route\n- For permission-based access, prefer `has({ permission: '...' })` over `has({ role: '...' })` -- permissions decouple authorization from role names\n- JWT templates support custom `iss`, `aud`, and `exp` claims for integrating with Hasura, Supabase, Convex, Neon, and other services\n- Organization switching changes the active session scope instantly -- no page reload needed\n\n## Resources\n- [clerkMiddleware() Reference](https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fnextjs\u002Fclerk-middleware)\n- [auth() Reference](https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fnextjs\u002Fapp-router\u002Fauth)\n- [Custom Session Tokens](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fcustomize-session-tokens)\n- [JWT Templates](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates)\n\n## Next Steps\nProceed to `clerk-webhooks-events` for webhook and event handling.\n\n",{"name":5,"tags":54,"author":55,"license":15,"version":56,"description":57,"allowed-tools":58,"compatible-with":59},[46,32,33,48,36],"Jeremy Longshore \u003Cjeremy@intentsolutions.io>","1.0.0","Implement session management and middleware with Clerk.\nUse when managing user sessions, configuring route protection,\nor implementing token refresh and custom JWT templates.\nTrigger with phrases like \"clerk session\", \"clerk middleware\",\n\"clerk route protection\", \"clerk token\", \"clerk JWT\".\n","Read, Write, Edit, Grep","claude-code, codex, openclaw","main","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Fjeremylongshore\u002Fclaude-code-plugins-plus-skills\u002Fclerk-core-workflow-b",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":8,"skillName":5,"commands":70,"prompt":80,"zipAvailable":81},[71,74,77],{"tool":72,"command":73},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill clerk-core-workflow-b",{"tool":75,"command":76},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill clerk-core-workflow-b",{"tool":78,"command":79},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill clerk-core-workflow-b","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fjeremylongshore\u002Fclaude-code-plugins-plus-skills\u002Fclerk-core-workflow-b\u002FSKILL.md",true,[],[84,94,104,113,119,126],{"skillNo":85,"name":86,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":90,"publishedAt":49},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[89],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[91,92,93],"model","model hierarchy","model hierarchy skill",{"skillNo":95,"name":96,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":100,"publishedAt":49},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[99],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[101,102,103],"MCP","zoom","zoom mcp",{"skillNo":105,"name":106,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":49},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[110,111,112,102],"sdk","zoom apps sdk","apps",{"skillNo":114,"name":115,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":49},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[115],{"skillNo":120,"name":121,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":125,"publishedAt":49},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[124],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[121],{"skillNo":127,"name":128,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":49},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[128]]