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