1# Middleware Strategies
2 
3> **Filename:** `proxy.ts` (Next.js <=15: `middleware.ts`). The code is identical; only the filename changes.
4 
5## Public-First (marketing sites, blogs)
6 
7Protect specific routes, allow everything else:
8 
9```typescript
10import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
11 
12const isProtectedRoute = createRouteMatcher([
13  '/dashboard(.*)',
14  '/settings(.*)',
15  '/api/private(.*)',
16]);
17 
18export default clerkMiddleware(async (auth, req) => {
19  if (isProtectedRoute(req)) await auth.protect();
20});
21 
22export const config = {
23  matcher: [
24    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
25    '/(api|trpc)(.*)',
26  ],
27};
28```
29 
30## Protected-First (internal tools, dashboards)
31 
32Block everything, allow specific public routes:
33 
34```typescript
35import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
36 
37const isPublicRoute = createRouteMatcher([
38  '/',
39  '/sign-in(.*)',
40  '/sign-up(.*)',
41  '/api/public(.*)',
42]);
43 
44export default clerkMiddleware(async (auth, req) => {
45  if (!isPublicRoute(req)) await auth.protect();
46});
47```
48 
49## Permission-Gated Routes
50 
51For B2B apps where some routes require a specific permission or role, pass a callback to `auth.protect()`. Clerk returns a 404 if the check fails:
52 
53```typescript
54import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
55 
56const isInvoiceRoute = createRouteMatcher(['/invoices(.*)']);
57const isAdminRoute = createRouteMatcher(['/admin(.*)']);
58 
59export default clerkMiddleware(async (auth, req) => {
60  if (isInvoiceRoute(req)) {
61    await auth.protect((has) => has({ permission: 'org:invoices:create' }));
62  }
63  if (isAdminRoute(req)) {
64    await auth.protect((has) =>
65      has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })
66    );
67  }
68});
69```
70 
71Prefer permissions over roles — permissions are more granular and easier to reassign across roles in the Dashboard.
72 
73> **Core 2 ONLY (skip if current SDK):** Middleware uses synchronous `clerkMiddleware((auth, req) => { auth().protect((has) => ...) })`. Note `auth()` is called as a function (not `auth.protect`) and the callback signature is the same.
74 
75## Token-Based Protection (Machine APIs)
76 
77For routes that accept different token types (OAuth tokens, machine-to-machine tokens, API keys), pass a `token` option to `auth.protect()`:
78 
79```typescript
80const isMachineApi = createRouteMatcher(['/api/machine(.*)']);
81const isPublicApi = createRouteMatcher(['/api/public(.*)']);
82 
83export default clerkMiddleware(async (auth, req) => {
84  if (isMachineApi(req)) await auth.protect({ token: 'm2m_token' });
85  if (isPublicApi(req)) await auth.protect({ token: 'any' });
86});
87```
88 
89Token types: `'session_token'` (default, browser sessions), `'oauth_token'`, `'api_key'`, `'m2m_token'`, `'any'` (accept any valid token).
90 
91> **Core 2 ONLY (skip if current SDK):** Token-type protection requires Core 3. In Core 2, `auth().protect()` only accepts a callback (no `token` option) and only validates session tokens.
92 
93## Session Tasks
94 
95When session tasks are enabled (e.g., forced password reset, MFA setup), users may have a `pending` session status. You can handle this in middleware:
96 
97```typescript
98export default clerkMiddleware(async (auth, req) => {
99  const { sessionStatus } = await auth();
100 
101  // Redirect pending sessions to task completion page
102  if (sessionStatus === 'pending') {
103    return NextResponse.redirect(new URL('/sign-in/tasks', req.url));
104  }
105 
106  if (isProtectedRoute(req)) await auth.protect();
107});
108```
109 
110> **Core 2 ONLY (skip if current SDK):** `sessionStatus` is not available. Session tasks do not exist in Core 2.
111 
112[Docs](https://clerk.com/docs/reference/nextjs/clerk-middleware)
113