## The Redirect-Based Auth Pattern That Needs to Die Most Next.js authentication failures stem from treating HTTP 302 redirects as a general-purpose error response. Middleware intercepts unauthorized requests, finds no valid session, and returns `NextResponse.redirect(new URL('/login', request.url))`. The browser follows the redirect, the user sees a login page, and the developer assumes this solves the problem. The pattern appears to work until search engines index protected content, API clients receive HTML instead of JSON errors, or authenticated users hit permission boundaries that trigger redirect loops. The fundamental issue is semantic. A redirect tells the client "the resource you want is somewhere else." A 401 Unauthorized says "you need credentials." A 403 Forbidden says "your credentials lack permission for this resource." When middleware redirects an API request to `/login`, the client receives a 302 status code pointing to an HTML login form instead of a machine-readable error. When a search crawler hits a protected route and gets redirected to `/login`, it indexes the login page URL as the canonical location for that protected content. When an authenticated user lacks permission for `/admin/settings`, a redirect to `/dashboard` hides the distinction between authentication failure and authorization failure. ```mermaid flowchart LR A("Request /admin/users") --> B("Middleware checks auth") B --> C("No session found") C --> D("HTTP 302 to /login") D --> E("Client receives HTML login page") style C stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style D stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style E stroke:#ef4444,fill:#450a0a,color:#fca5a5 ``` Next.js 15 introduced `forbidden()` and `unauthorized()` to fix this. These functions throw errors that App Router catches and converts to proper HTTP responses: 403 for `forbidden()`, 401 for `unauthorized()`. Instead of redirecting users away from protected routes, developers can return semantic status codes that preserve the request URL, communicate intent to clients, and trigger appropriate browser behavior like credential prompts. ```mermaid flowchart LR A("Request /admin/users") --> B("Server Component checks auth") B --> C("No session found") C --> D("unauthorized() throws") D --> E("HTTP 401 response") E --> F("Browser triggers auth flow") style D stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style F stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` The shift from redirect-based guards to semantic HTTP responses changes how teams structure authentication, how browsers handle protected routes, and how API clients consume Next.js backends. That covers the problem. The rest of this post shows the implementation. ## Key Takeaways - `forbidden()` and `unauthorized()` replace middleware redirects with proper HTTP 403 and 401 status codes that preserve request URLs and communicate intent to clients. - Use `unauthorized()` when credentials are missing or invalid; use `forbidden()` when valid credentials lack permission for a specific resource. - Server Components that call these functions throw errors App Router catches and converts to HTTP responses, eliminating the need for redirect-based middleware patterns. - Search engines, API clients, and browser credential managers all depend on correct HTTP status codes to handle authentication failures properly. - Combining these functions with `notFound()` and `redirect()` creates a complete vocabulary for semantic route protection in App Router. ## Next.js 15+ forbidden() and unauthorized(): Semantic HTTP Responses for App Router The `forbidden()` and `unauthorized()` functions live in `next/navigation` and throw errors that App Router intercepts during server-side rendering. App Router converts `forbidden()` to an HTTP 403 Forbidden response and `unauthorized()` to an HTTP 401 Unauthorized response. Unlike redirects that send the client to a different URL, these responses keep the original request URL intact while signaling the reason access failed. This distinction matters for browser credential managers, HTTP caching, and machine-readable error handling. ```typescript import { unauthorized, forbidden } from 'next/navigation'; import { getSession } from '@/lib/auth'; export default async function AdminPage() { const session = await getSession(); if (!session) { unauthorized(); } if (session.user.role !== 'admin') { forbidden(); } return ; } ``` When this Server Component renders, the authentication check happens before any JSX returns. If `getSession()` finds no valid session, `unauthorized()` throws an error that halts rendering. App Router catches the error, returns an HTTP 401 response to the browser, and the browser can trigger its built-in credential prompt or OAuth flow. If the session exists but the user lacks admin privileges, `forbidden()` throws instead, producing an HTTP 403 that tells the browser "you're authenticated, but this resource is off-limits." ```mermaid flowchart TD A("Browser requests /admin") --> B("Server Component renders") B --> C("getSession() called") C --> D("Session exists?") D -->|"No"| E("unauthorized() throws") D -->|"Yes"| F("Role is admin?") F -->|"No"| G("forbidden() throws") F -->|"Yes"| H("Return JSX") E --> I("HTTP 401 response") G --> J("HTTP 403 response") H --> K("HTML page rendered") style E stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style G stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style I stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style J stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style K stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` The browser receives a response with the correct status code and can handle it appropriately. The request URL stays `/admin` instead of changing to `/login`, so bookmarks and history entries preserve the user's intent. API clients parsing the response see a 401 or 403 status code instead of receiving HTML from a login page. Search crawlers understand that the content requires authentication and avoid indexing it as public content. This pattern works in any Server Component, Server Action, or Route Handler. The key requirement is that the code runs on the server during the request lifecycle, not in client-side hydration or state updates. App Router's error boundary system handles the thrown error and converts it to the appropriate HTTP response before sending anything to the client. ## Replacing Middleware Redirects with forbidden() and unauthorized() The redirect-based middleware pattern looks like this in most Next.js codebases: ```typescript // middleware.ts (old pattern) import { NextResponse } from 'next/server'; import type { NextRequest } from 'next/server'; export function middleware(request: NextRequest) { const sessionToken = request.cookies.get('session'); if (!sessionToken && request.nextUrl.pathname.startsWith('/admin')) { return NextResponse.redirect(new URL('/login', request.url)); } return NextResponse.next(); } export const config = { matcher: ['/admin/:path*'], }; ``` This middleware intercepts every request to `/admin/*`, checks for a session cookie, and redirects to `/login` if missing. The browser follows the redirect, the URL bar changes, and the user sees the login page. The problem surfaces when search engines crawl `/admin/users` and get redirected to `/login`, indexing the login URL as the canonical resource. When API clients request `/admin/api/stats`, they receive an HTML login page instead of a 401 JSON response. The semantic approach moves authentication checks into the Server Component and returns proper HTTP status codes: ```typescript // app/admin/page.tsx (new pattern) import { unauthorized } from 'next/navigation'; import { getSession } from '@/lib/auth'; export default async function AdminLayout({ children, }: { children: React.ReactNode; }) { const session = await getSession(); if (!session) { unauthorized(); } return <>{children}; } ``` Now when a request hits `/admin/users` without credentials, the Server Component throws via `unauthorized()`, App Router returns HTTP 401, and the browser stays on `/admin/users`. The URL preservation lets users bookmark protected routes, lets OAuth flows redirect back to the original destination, and lets error tracking tools log the actual resource users attempted to access. Middleware still has a role for cross-cutting concerns like rate limiting, request logging, and header manipulation. Authentication checks belong in Server Components where developers have access to database queries, session parsing, and React's composition model. The separation improves testability: testing a Server Component's auth logic requires mocking `getSession()`, while testing middleware requires constructing synthetic `NextRequest` objects and URL patterns. For routes that need granular permission checks beyond presence-of-session, `forbidden()` handles the distinction: ```typescript import { unauthorized, forbidden } from 'next/navigation'; import { getSession } from '@/lib/auth'; import { getUserPermissions } from '@/lib/permissions'; export default async function ResourcePage({ params, }: { params: { id: string }; }) { const session = await getSession(); if (!session) { unauthorized(); } const permissions = await getUserPermissions(session.user.id); if (!permissions.includes('resource:read')) { forbidden(); } const resource = await getResource(params.id); return ; } ``` This pattern makes authorization failures distinct from authentication failures. A 401 response tells the client "you need to log in," while a 403 response says "you're logged in, but you don't have permission." The HTTP semantics align with standard REST conventions, making Next.js backends compatible with generic API clients that expect these status codes. ## forbidden() vs unauthorized() vs redirect(): When to Use Each The three functions solve different problems in route protection. Choosing the wrong one produces subtle bugs that appear as edge cases until production traffic reveals the failure mode. ```mermaid flowchart LR subgraph Request["Incoming Request"] A("User accesses protected route") end subgraph Check["Auth Check"] B("Has valid session?") C("Has required permission?") D("Should access different resource?") end subgraph Response["HTTP Response"] E("unauthorized(): 401") F("forbidden(): 403") G("redirect(): 302") end A --> B B -->|"No"| E B -->|"Yes"| C C -->|"No"| F C -->|"Yes"| D D -->|"No"| H("Return content") D -->|"Yes"| G style E stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style F stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style G stroke:#7c9cf0,fill:#142544,color:#eaf2ff style H stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Use `unauthorized()` when the request lacks valid credentials. The client needs to authenticate before accessing the resource. Typical scenarios include expired session tokens, missing JWT headers, or OAuth flows that haven't completed. The HTTP 401 status code triggers browser credential prompts and signals to API clients that they should retry with authentication. Use `forbidden()` when valid credentials exist but lack permission for the specific resource. The user is authenticated but not authorized. Typical scenarios include role-based access control failures, resource ownership checks that fail, or feature flags that disable access for certain user tiers. The HTTP 403 status code tells clients "you can't access this, and re-authenticating won't help." Use `redirect()` when the request should access a different resource entirely. The URL the client requested is not what they should see. Typical scenarios include post-login navigation, feature deprecation redirects, or URL normalization. The HTTP 302 status code tells clients "what you want is at this other URL" and changes the browser's location. The distinction becomes critical when combining these functions in nested layouts: ```typescript // app/admin/layout.tsx import { unauthorized } from 'next/navigation'; import { getSession } from '@/lib/auth'; export default async function AdminLayout({ children, }: { children: React.ReactNode; }) { const session = await getSession(); if (!session) { unauthorized(); } return {children}; } // app/admin/settings/page.tsx import { forbidden } from 'next/navigation'; import { getSession } from '@/lib/auth'; export default async function SettingsPage() { const session = await getSession(); if (session.user.role !== 'owner') { forbidden(); } return ; } ``` The layout handles authentication, the page handles authorization. An unauthenticated request to `/admin/settings` throws in the layout via `unauthorized()`, returning HTTP 401. An authenticated non-owner request makes it through the layout but throws in the page via `forbidden()`, returning HTTP 403. The nested composition lets developers express permission hierarchies without duplicating auth logic. A redirect belongs in success paths, not failure paths: ```typescript import { redirect } from 'next/navigation'; import { getSession } from '@/lib/auth'; export default async function LoginPage() { const session = await getSession(); if (session) { redirect('/dashboard'); } return ; } ``` This pattern redirects authenticated users away from the login page to their dashboard. The redirect happens in the success case (session exists), not the failure case (no session). Using `redirect()` for authentication failures inverts the semantic meaning and breaks HTTP caching, browser history, and API client error handling. ## Building Production-Ready Auth Guards with Proper HTTP Semantics Production authentication systems need more than session presence checks. Teams need permission boundaries, resource ownership validation, feature flag enforcement, and rate limiting. The semantic HTTP approach scales to these requirements by composing small functions that throw or return. ```typescript // lib/auth-guards.ts import { unauthorized, forbidden } from 'next/navigation'; import { getSession } from './auth'; import { getUserPermissions } from './permissions'; export async function requireAuth() { const session = await getSession(); if (!session) { unauthorized(); } return session; } export async function requireRole(role: string) { const session = await requireAuth(); if (session.user.role !== role) { forbidden(); } return session; } export async function requirePermission(permission: string) { const session = await requireAuth(); const permissions = await getUserPermissions(session.user.id); if (!permissions.includes(permission)) { forbidden(); } return session; } export async function requireOwnership(resourceId: string) { const session = await requireAuth(); const resource = await getResource(resourceId); if (resource.ownerId !== session.user.id) { forbidden(); } return { session, resource }; } ``` These guards compose together in Server Components: ```typescript import { requirePermission } from '@/lib/auth-guards'; export default async function BillingPage() { await requirePermission('billing:manage'); const invoices = await getInvoices(); return ; } ``` The guard throws if permission checks fail, halting component rendering and returning HTTP 403. If the check passes, the function returns the session and rendering continues. The pattern reads like synchronous code but handles async database queries and session parsing without callback nesting. ```mermaid flowchart LR A("Request /billing") --> B("requirePermission called") B --> C("getSession()") C --> D("Session exists?") D -->|"No"| E("unauthorized() throws") D -->|"Yes"| F("getUserPermissions()") F --> G("Has billing:manage?") G -->|"No"| H("forbidden() throws") G -->|"Yes"| I("Return session") I --> J("Render component") style B stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style H stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style J stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Resource ownership checks follow the same pattern: ```typescript import { requireOwnership } from '@/lib/auth-guards'; export default async function ProjectPage({ params, }: { params: { id: string }; }) { const { session, resource } = await requireOwnership(params.id); return ; } ``` The guard returns both session and resource, eliminating duplicate database queries. If ownership validation fails, the component throws via `forbidden()` before rendering. If it succeeds, the component has both the authenticated user and the owned resource in scope. Feature flags integrate without special handling: ```typescript export async function requireFeature(feature: string) { const session = await requireAuth(); const features = await getUserFeatures(session.user.id); if (!features.includes(feature)) { forbidden(); } return session; } ``` The guard throws `forbidden()` for users without the feature, returning HTTP 403. This communicates "you're authenticated, but this feature isn't available to you" instead of redirecting to a generic error page. API clients can parse the 403 and show appropriate upgrade prompts or feature previews. Server Actions use the same guards: ```typescript 'use server'; import { requirePermission } from '@/lib/auth-guards'; import { revalidatePath } from 'next/cache'; export async function deleteProject(projectId: string) { await requirePermission('projects:delete'); await db.projects.delete({ where: { id: projectId } }); revalidatePath('/projects'); } ``` When a client calls this Server Action without the required permission, the action throws via `forbidden()` before executing the delete. Next.js converts the error to an HTTP 403 response that the client can handle with error boundaries or toast notifications. ## Edge Cases: Search Engines, Client Components, and API Routes Search engine crawlers expect HTTP status codes to signal content availability. A redirect-based auth pattern returns HTTP 302 for protected routes, and crawlers follow the redirect to the login page. Google indexes the login URL as the canonical location for the protected content, creating duplicate content issues and exposing protected route structures in search results. With `unauthorized()`, the crawler receives HTTP 401, understands the content requires authentication, and excludes it from search results: ```typescript import { unauthorized } from 'next/navigation'; import { getSession } from '@/lib/auth'; export default async function MemberContentPage() { const session = await getSession(); if (!session) { unauthorized(); } return ; } ``` The crawler sees HTTP 401, marks the page as requiring credentials, and moves on. No redirect loop, no indexed login page, no leaked route structure. This behavior aligns with standard HTTP semantics that crawlers already handle correctly for traditional server applications. ```mermaid flowchart LR A("Crawler requests /members/content") --> B("Server Component renders") B --> C("getSession() returns null") C --> D("unauthorized() throws") D --> E("HTTP 401 response sent") E --> F("Crawler marks page as auth-required") F --> G("Page excluded from index") style D stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style G stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Client Components cannot call `unauthorized()` or `forbidden()` directly because these functions throw errors during rendering, and client-side errors don't convert to HTTP responses. The pattern requires Server Components to handle authentication before rendering Client Components: ```typescript // app/dashboard/page.tsx (Server Component) import { requireAuth } from '@/lib/auth-guards'; import { DashboardClient } from './DashboardClient'; export default async function DashboardPage() { const session = await requireAuth(); return ; } // app/dashboard/DashboardClient.tsx (Client Component) 'use client'; export function DashboardClient({ user }: { user: User }) { return

Welcome, {user.name}

; } ``` The Server Component calls `requireAuth()`, which throws if authentication fails. If it succeeds, the Server Component renders the Client Component with the authenticated user as a prop. The Client Component receives the user and assumes authentication succeeded because it only renders after the guard passes. For client-side navigation that needs to check permissions before triggering mutations, use Server Actions: ```typescript 'use server'; import { requirePermission } from '@/lib/auth-guards'; export async function publishPost(postId: string) { await requirePermission('posts:publish'); await db.posts.update({ where: { id: postId }, data: { published: true }, }); } ``` The Client Component calls this Server Action when the user clicks "Publish." The Server Action checks permissions before executing. If the check fails, the action throws via `forbidden()`, and Next.js returns an error the Client Component can catch with error boundaries or try-catch blocks. Route Handlers use the same pattern: ```typescript import { unauthorized, forbidden } from 'next/navigation'; import { getSession } from '@/lib/auth'; export async function GET() { const session = await getSession(); if (!session) { unauthorized(); } if (session.user.role !== 'admin') { forbidden(); } const data = await getAdminData(); return Response.json(data); } ``` When an API client requests this endpoint without credentials, the Route Handler throws via `unauthorized()`, and Next.js returns an HTTP 401 response with no body. The client sees the 401 status code and can retry with authentication. Unlike a redirect that returns HTML, this response is machine-readable and follows REST conventions. For API routes that need custom error messages, construct a `Response` object before throwing: ```typescript export async function GET() { const session = await getSession(); if (!session) { return new Response( JSON.stringify({ error: 'Authentication required' }), { status: 401, headers: { 'Content-Type': 'application/json' } } ); } const data = await getData(); return Response.json(data); } ``` This pattern gives more control over the response body while maintaining correct HTTP semantics. The client receives a 401 status code with a JSON error message instead of an empty response. ## Frequently Asked Questions ### Can I use forbidden() and unauthorized() in middleware? No. Middleware runs before App Router's rendering phase, so throwing errors there does not trigger App Router's error boundary system. Middleware should return `NextResponse` objects for redirects or custom responses, while Server Components and Route Handlers use `forbidden()` and `unauthorized()` for semantic HTTP errors. ### What happens when a user bookmarks a protected route and visits it later? The browser requests the bookmarked URL, the Server Component checks authentication, and if the session expired, `unauthorized()` throws and returns HTTP 401. The URL stays intact, so OAuth flows or login redirects can send the user back to the original bookmark after authentication completes. ### How do I customize the error page shown for 401 and 403 responses? Create `unauthorized.tsx` and `forbidden.tsx` files in your `app` directory. Next.js renders these components when the corresponding errors occur, letting you show custom error UI while preserving the HTTP status code. ### Do these functions work with streaming Server Components? Yes. If an error occurs during streaming, Next.js cancels the stream and returns the error response. The HTTP status code changes to 401 or 403, and the partial HTML sent before the error is discarded. ### Should I still use middleware for authentication? Middleware handles cross-cutting concerns like rate limiting and request logging. Authentication checks belong in Server Components where you have access to database queries and React composition. The separation improves testability and aligns with App Router's server-first architecture. ## Why Semantic HTTP Responses Matter Beyond Auth The shift from redirects to semantic HTTP responses changes how developers think about error handling in Next.js applications. `unauthorized()` and `forbidden()` join `notFound()` as part of a vocabulary for expressing routing outcomes through HTTP semantics instead of control flow patterns. When teams treat HTTP status codes as a communication protocol between server and client, they build systems that work correctly with browsers, search engines, and API clients without special-case handling. A 401 response tells all three "credentials required." A 403 response says "permission denied." A 404 response means "resource not found." These signals work the same whether the client is a human with a browser, a crawler with an indexer, or a script with an HTTP library. The pattern extends beyond authentication. Server Components that validate input can throw errors App Router converts to 400 Bad Request. Components that hit rate limits can return 429 Too Many Requests. Components that encounter server errors can throw and let Next.js return 500 Internal Server Error. The error boundary system handles the conversion, and developers write straightforward validation logic that throws when checks fail. That covers the essential patterns for semantic HTTP responses in Next.js App Router. Replace middleware redirects with `unauthorized()` and `forbidden()` in Server Components, compose small guard functions that throw or return, and let App Router convert errors to proper HTTP status codes. Apply these in production and the difference will be immediate.

Posts tagged “git”

Parallel AI Coding with Git Worktrees: Run Multiple Agents Without Conflicts