菜单
Implement session management and middleware with Clerk. Use when managing user sessions, configuring route protection, or implementing token refresh and custom JWT templates. Trigger with phrases like "clerk session", "clerk middleware", "clerk route protection", "clerk token", "clerk JWT".
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ComeOnOliver/skillshub --skill clerk-core-workflow-b命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Review product and feature risk before an AI coding agent starts implementation.
Use Xquik for X data and confirmation-gated X actions: tweet search, user lookup, follower export, media download, monitors, webhooks, MCP, and SDK workflows.
Canton Network open-source ecosystem guide covering DAML SDK, Canton runtime, and Splice applications. Use when working with Canton Network, DAML smart contracts, or building decentralized applications.
基于 SOC 职业分类
正在显示 SKILL.md
| name | clerk-core-workflow-b |
| description | Implement session management and middleware with Clerk. Use when managing user sessions, configuring route protection, or implementing token refresh and custom JWT templates. Trigger with phrases like "clerk session", "clerk middleware", "clerk route protection", "clerk token", "clerk JWT". |
| allowed-tools | Read, Write, Edit, Grep |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| compatible-with | claude-code, codex, openclaw |
| tags | ["saas","clerk","clerk-core","sessions","middleware"] |
Implement 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.
@clerk/nextjs installed with ClerkProvider wrapping the appclerk-core-workflow-a completed)// middleware.ts (project root)
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isPublicRoute = createRouteMatcher([
'/',
'/sign-in(.*)',
'/sign-up(.*)',
'/api/webhooks(.*)',
'/pricing',
'/blog(.*)',
])
const isAdminRoute = createRouteMatcher(['/admin(.*)'])
const isApiRoute = createRouteMatcher(['/api(.*)'])
export default clerkMiddleware(async (auth, req) => {
// Public routes: no auth required
if (isPublicRoute(req)) return
// Admin routes: require org:admin role
if (isAdminRoute(req)) {
await auth.protect({ role: 'org:admin' })
return
}
auth.()
})
config = {
: [
,
,
],
}
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.
// app/api/data/route.ts
import { auth } from '@clerk/nextjs/server'
export async function GET() {
const { userId, orgId, has } = await auth()
if (!userId) {
return Response.json({ error: 'Unauthorized' }, { status: 401 })
}
// Permission-based authorization
if (!has({ permission: 'org:data:read' })) {
return Response.json({ error: 'Forbidden' }, { status: 403 })
}
const data = orgId
? await db.items.findMany({ where: { organizationId: orgId } })
: await db.items.findMany({ where: { ownerId: userId } })
return Response.json({ data, userId, orgId })
}
export async function POST(req: Request) {
const { userId, orgId, has } = await auth()
if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })
if (!has({ permission: 'org:data:write' })) {
return Response.json({ error: 'Forbidden' }, { status: 403 })
}
const body = await req.json()
const item = await db.items.create({
data: { ...body, ownerId: userId, organizationId: orgId },
})
return Response.json({ item }, { status: 201 })
}
// app/dashboard/page.tsx
import { auth, currentUser } from '@clerk/nextjs/server'
import { redirect } from 'next/navigation'
export default async function DashboardPage() {
const { userId, orgId, orgRole, has, sessionClaims } = await auth()
if (!userId) redirect('/sign-in')
// auth() is free (JWT parsing) — use for lightweight checks
const isAdmin = has({ role: 'org:admin' })
// currentUser() costs a Backend API call — use only when you need full profile
const user = await currentUser()
return (
<div>
<h1>Welcome, {user?.firstName}</h1>
<p>Organization: {orgId || 'Personal account'}</p>
<p>Role: {orgRole || 'N/A'}</p>
{isAdmin && <a href="/admin">Admin Panel</a>}
</div>
)
}
Customize in Dashboard > Sessions > Customize session token:
{
"metadata": "{{user.public_metadata}}",
"email": "{{user.primary_email_address}}"
}
Then declare types and access in code:
// types/clerk.d.ts
declare global {
interface CustomJwtSessionClaims {
metadata?: {
role?: string
plan?: string
}
email?: string
}
}
export {}
// Access custom claims (no API call needed — embedded in JWT)
import { auth } from '@clerk/nextjs/server'
export async function GET() {
const { sessionClaims } = await auth()
const userPlan = sessionClaims?.metadata?.plan || 'free'
const userEmail = sessionClaims?.email
return Response.json({ plan: userPlan, email: userEmail })
}
Warning: Session token cookie limit is 4KB. Custom claims should be under 1.2KB. Store large data in your database, not in session claims.
// app/api/supabase-data/route.ts
import { auth } from '@clerk/nextjs/server'
import { createClient } from '@supabase/supabase-js'
export async function GET() {
const { userId, getToken } = await auth()
if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })
// Get a JWT with Supabase-compatible claims
// Configure the template in Dashboard > JWT Templates
const supabaseToken = await getToken({ template: 'supabase' })
const supabase = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{ global: { headers: { Authorization: `Bearer ${supabaseToken}` } } }
)
const { data } = await supabase.from('items').select('*')
return Response.json({ data })
}
Configure JWT template in Dashboard > JWT Templates > New template:
{
"sub": "{{user.id}}",
"email": "{{user.primary_email_address}}",
"role": "authenticated",
"aud": "authenticated"
}
'use client'
import { useOrganizationList, useOrganization, useAuth } from '@clerk/nextjs'
export function OrgSwitcher() {
const { organizationList, setActive, isLoaded } = useOrganizationList({
userMemberships: { infinite: true },
})
const { organization } = useOrganization()
if (!isLoaded) return <div>Loading orgs...</div>
return (
<div>
<p>Active: {organization?.name || 'Personal account'}</p>
<ul>
{organizationList?.map(({ organization: org, membership }) => (
<li key={org.id}>
<button onClick={() => setActive({ organization: org.id })}>
{org.name} ({membership.role})
</button>
</li>
))}
<li>
<button onClick={() => setActive({ organization: null })}>
Personal account
</button>
</li>
</ul>
</div>
)
}
'use server'
import { auth } from '@clerk/nextjs/server'
export async function deleteItem(itemId: string) {
const { userId, orgId, has } = await auth()
if (!userId) throw new Error('Unauthorized')
if (!has({ permission: 'org:data:delete' })) {
throw new Error('You do not have permission to delete items')
}
await db.items.delete({ where: { id: itemId, organizationId: orgId } })
return { success: true }
}
export async function updateOrgSettings(settings: Record<string, any>) {
const { orgId, has } = await auth()
if (!orgId) throw new Error('No organization selected')
if (!has({ role: 'org:admin' })) {
throw new Error('Only admins can update organization settings')
}
await db.orgSettings.upsert({
where: { orgId },
update: settings,
create: { orgId, ...settings },
})
return { success: true }
}
| Issue | Cause | Solution |
|---|---|---|
| Middleware redirect loop | Sign-in page not in isPublicRoute | Add /sign-in(.*) to public route matcher |
| 401 on API route | Token not forwarded | Include credentials in fetch or use server-side auth() |
orgId is null | No active organization | Prompt user with <OrganizationSwitcher /> |
has() always false | Permission not assigned to role | Check Dashboard > Organizations > Roles |
| Session expired | Token TTL exceeded | Clerk auto-refreshes; if stuck, clear cookies |
auth() was called but clerkMiddleware() not detected | Middleware missing or wrong location | Ensure middleware.ts at project root |
auth.protect() in middleware returns a 401/redirect before reaching your route handler -- this is more efficient than checking userId in every routehas({ permission: '...' }) over has({ role: '...' }) -- permissions decouple authorization from role namesiss, aud, and exp claims for integrating with Hasura, Supabase, Convex, Neon, and other servicesProceed to clerk-webhooks-events for webhook and event handling.