Next.js Middleware: Expired Credential Response Strategy at the Edge Runtime Boundary

Direct Answer

For expired credentials in Next.js App Router middleware, redirect browser page navigations to the sign-in page with a callbackUrl and return 401 for API/fetch/XHR requests. This distinction prevents API clients from following an HTML redirect and receiving a 200 login page instead of a proper unauthorized response.

Why This Split Matters

The App Router treats navigation and data requests differently. A browser navigation that receives a 307 redirect to /sign-in?callbackUrl=... will follow it and render the sign-in page, then return the user to the original route after authentication. An API request that receives the same redirect may follow it (depending on redirect fetch options) and parse HTML as JSON, causing parsing errors and masking the real auth failure. Returning 401 with {error: 'unauthorized'} lets client-side code (e.g., next-auth client, SWR, TanStack Query) clear the session and trigger a re-auth flow without a full page reload.

Edge Runtime Crypto Reality

The Edge runtime provides Web Crypto (crypto.subtle), not the full Node.js crypto module. HMAC-SHA256 JWT verification (HS256) is practical; RSA/ECDSA verification (RS256, ES256) works but consumes more CPU and may approach the 1.5 s Vercel function limit if keys are large or rotation is frequent. Next.js 15 does not add Node crypto to Edge middleware—support depends on the underlying Edge runtime version (Vercel, Cloudflare, Netlify). Verify on your target deployment with a minimal middleware that calls crypto.subtle.importKey or crypto.subtle.verify and confirm it does not throw.

next-auth v4 vs v5 (Auth.js Beta)

• v4: getToken({ req, secret }) verifies the existing JWT in middleware. It returns the decoded token or null if expired/invalid. No automatic refresh of expired access tokens occurs; you must implement a dedicated refresh endpoint that reads the refresh token (usually stored in an HttpOnly cookie) and issues a new access token.
• v5 (beta): Middleware APIs and token-refresh behavior are not stable. Do not assume automatic refresh or identical getToken signatures. Check the current Auth.js documentation before relying on v5 in production.

Minimal Middleware Pattern

import { NextResponse } from 'next/server'
import { getToken } from 'next-auth/jwt'

export async function middleware(request) {
  const token = await getToken({ req: request, secret: process.env.NEXTAUTH_SECRET })
  const isApi = request.nextUrl.pathname.startsWith('/api') ||
                request.headers.get('accept')?.includes('application/json')

  if (!token) {
    return isApi
      ? NextResponse.json({ error: 'unauthorized' }, { status: 401 })
      : NextResponse.redirect(new URL(`/sign-in?callbackUrl=${encodeURIComponent(request.url)}`, request.url), 307)
  }
  return NextResponse.next()
}

export const config = { matcher: ['/dashboard/:path*', '/api/protected/:path*'] }

Verification Checklist

1. Deploy a test middleware that calls crypto.subtle.digest('SHA-256', new TextEncoder().encode('test')) and confirm it executes without error on your hosting provider.
2. Inject an expired JWT (e.g., set exp to past timestamp) and verify middleware returns 401 for /api/... and 307 redirect for page routes.
3. Confirm getToken returns null for the expired token and does not invoke any refresh callback.
4. Review your provider's Edge function limits (CPU time, memory) and Web Crypto availability in their current docs.

One Diagnostic Detail Needed

Which hosting provider and runtime version are you targeting? (Vercel Edge Functions, Cloudflare Workers, Netlify Edge Functions, self-hosted). This determines the exact Web Crypto support and CPU budget, which changes whether RSA/ECDSA verification is viable or if you should migrate to HS256 / JWKS caching.