---
name: jeremylongshore/clerk-core-workflow-b
source: https://app.decimal.ai/s/jeremylongshore-clerk-core-workflow-b@1/SKILL.md
source_sha256: c1c2e600ca7e
---

# 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

1. Confirm ClerkProvider and env keys are live (see `clerk-install-auth` / `clerk-hello-world`).
2. Configure `clerkMiddleware()` matcher / public routes for the routes you want open.
3. Use `auth()` / `currentUser()` on protected pages and API routes; fail closed when unauthenticated.
4. For custom claims or external JWT consumers, configure session token templates carefully (size limits).
5. For org-scoped apps, bind authorization to org id + role claims, not only user id.
6. 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](references/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.
```