clerk-core-workflow-b

Clerk Core Workflow B: Session & Middleware

Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Implement session management and route protection with Clerk middleware. Covers Next.js middleware configuration, API route protection, role-based access control, and organization-scoped sessions.

Prerequisites

• Clerk account with application created
• @clerk/nextjs package installed
• Next.js 14+ with App Router
• Understanding of JWT session tokens

Instructions

Step 1: Configure Clerk Middleware

Create middleware.ts at project root. Define public routes (landing, sign-in, webhooks) and admin routes. Use clerkMiddleware with auth.protect() for private routes and role-based protection for admin routes.

Step 2: Protect API Routes

Use auth() in route handlers to get userId, orgId, and has() for permission checks. Return 401/403 for unauthorized/insufficient permissions.

Step 3: Handle Session Claims

Access session data, user profile, and generate JWT tokens for external APIs (Supabase, etc.) using getToken({ template: 'name' }).

Step 4: Add Server Component Auth

Use auth() in server components with redirect('/sign-in') for unauthenticated users. Check roles/permissions with has() for conditional UI rendering.

See detailed implementation for complete middleware config, API route examples, session claims, server component patterns, and role-based navigation.

Output

• Middleware protecting all non-public routes
• API routes with auth and permission checks
• Server components with role-based rendering
• JWT tokens configured for external services

Error Handling

Issue	Cause	Solution
Middleware redirect loop	Public route not in matcher	Add route to isPublicRoute
401 on API route	Token not forwarded	Ensure fetch includes credentials
Missing org context	User not in organization	Check orgId before org-scoped ops
Session expired	Token TTL exceeded	Configure session lifetime in dashboard

Examples

Quick Permission Check

const { has } = await auth();
if (has({ permission: 'org:data:write' })) {
  // User can write data in this organization
}

Resources

• Clerk Middleware
• Clerk Auth Helper
• Clerk Organizations