| 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.14.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","clerk","clerk-core","sessions","middleware"] |
| compatibility | Designed for Claude Code |
Clerk Core Workflow B: Session & Middleware
Overview
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.
Use when managing user sessions, configuring route protection, or implementing
token refresh and custom JWT templates.
Prerequisites
@clerk/nextjs installed with ClerkProvider wrapping the app- Next.js 14+ with App Router (or adapt patterns for your stack)
- Working publishable + secret Clerk keys in env
Instructions
- Confirm ClerkProvider and env keys are live (see
clerk-install-auth / clerk-hello-world).
- Configure
clerkMiddleware() matcher / public routes for the routes you want open.
- Use
auth() / currentUser() on protected pages and API routes; fail closed when unauthenticated.
- For custom claims or external JWT consumers, configure session token templates carefully (size limits).
- For org-scoped apps, bind authorization to org id + role claims, not only user id.
- Verify: signed-out user cannot hit protected routes; signed-in user can; org role gates hold.
Deep patterns, JWT templates, and edge cases: session-middleware-deep-dive.md.
Output
- Session/middleware configuration enforcing the requested protection rules
- Documented JWT/session claim changes when customized
- Verification steps for protected vs public routes
Examples
Protect all routes except marketing
User: Protect everything except /, /pricing, and Clerk sign-in routes.
Skill: configures clerkMiddleware publicRoutes / matcher and verifies unauth redirect.
Custom session claim for plan tier
User: Put plan_tier on the session JWT for feature flags.
Skill: configures session token template and validates claim size + read path.
