Skip to main content
The applyResponseHeaders function applies AuthKit response headers to a Next.js NextResponse object. This low-level utility is used when creating custom middleware responses with rewrites or advanced routing.
Most users should use handleAuthkitHeaders instead, which handles both request and response headers automatically. Use applyResponseHeaders only for advanced use cases like rewrites.

​
Function signature

function applyResponseHeaders(
  response: NextResponse,
  responseHeaders: Headers
): NextResponse

​
Parameters

​
response
NextResponse
required
The Next.js response object to modify.
​
responseHeaders
Headers
required
The response headers from partitionAuthkitHeaders containing only allowlisted headers safe for the browser.

​
Returns

​
NextResponse
NextResponse
The same response object with headers applied. The function mutates the response and returns it for convenience.

​
Header merging behavior

The function properly merges headers according to their type:
  • Multi-value headers (Set-Cookie, Link, etc.) - Appends values instead of replacing
  • Vary header - Merges unique values with comma separation
  • Other headers - Sets or replaces the value

​
Examples

​
Basic usage with rewrites

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { 
  authkit, 
  partitionAuthkitHeaders, 
  applyResponseHeaders 
} from '@workos-inc/authkit-nextjs';

export default async function middleware(request: NextRequest) {
  const { headers } = await authkit(request);
  const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, headers);

  // Create a rewrite response
  const response = NextResponse.rewrite(
    new URL('/app/dashboard', request.url),
    { request: { headers: requestHeaders } }
  );

  // Apply AuthKit response headers (cookies, cache-control, etc.)
  return applyResponseHeaders(response, responseHeaders);
}

​
Dynamic routing with session data

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { 
  authkit, 
  partitionAuthkitHeaders, 
  applyResponseHeaders 
} from '@workos-inc/authkit-nextjs';

export default async function middleware(request: NextRequest) {
  const { session, headers } = await authkit(request);
  const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, headers);

  // Route based on user role
  let destination = '/app/dashboard';
  if (session.user) {
    const role = session.role;
    if (role === 'admin') {
      destination = '/app/admin';
    } else if (role === 'member') {
      destination = '/app/member';
    }
  }

  const response = NextResponse.rewrite(
    new URL(destination, request.url),
    { request: { headers: requestHeaders } }
  );

  return applyResponseHeaders(response, responseHeaders);
}

​
Custom response with headers

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { 
  authkit, 
  partitionAuthkitHeaders, 
  applyResponseHeaders 
} from '@workos-inc/authkit-nextjs';

export default async function middleware(request: NextRequest) {
  const { session, headers } = await authkit(request);
  const { responseHeaders } = partitionAuthkitHeaders(request, headers);

  // Create a custom JSON response
  const response = NextResponse.json(
    { authenticated: !!session.user },
    { status: 200 }
  );

  // Apply AuthKit headers to the JSON response
  return applyResponseHeaders(response, responseHeaders);
}

​
Which headers are applied?

The function applies only allowlisted response headers:
HeaderPurpose
Set-CookieSession cookies (appended, not replaced)
Cache-ControlCaching directives for authenticated responses
VaryCache variation keys (merged)
WWW-AuthenticateAuthentication challenges
Proxy-AuthenticateProxy authentication
LinkPagination, preload hints (appended)
x-middleware-cacheNext.js middleware caching control
Internal AuthKit headers (like x-workos-session) are filtered out by partitionAuthkitHeaders and never appear in response headers sent to the browser.

​
When to use this function

Use applyResponseHeaders when you need:
Creating NextResponse.rewrite() responses that need AuthKit headers.
Building JSON, image, or other custom responses that should include session cookies.
Full control over response creation while still properly applying AuthKit headers.

handleAuthkitHeaders

High-level helper for most use cases

partitionAuthkitHeaders

Separate request and response headers

Composable middleware

Complete middleware composition guide

Build docs developers (and LLMs) love

Get started for freeTalk to us