Auth Proxy Configuration

The createAuthProxy function creates a Next.js proxy that handles all authentication logic. This page covers all configuration options.

Basic Setup#

Configuration Options#

apiBaseUrl#

Required - Your backend API base URL.

cookies#

Required - Cookie configuration for token storage.

Dual-token mode is enabled simply by naming a refresh cookie. The user cookie becomes a short-lived access token and the refresh cookie a separate, long-lived token sent only to the refresh endpoint. See Token Management.

endpoints#

Backend endpoints for auth operations. All paths are relative to apiBaseUrl.

guestToken#

Configure guest token behavior.

access#

Route access control configuration.

i18n#

Internationalization support. Extracts locale from URL path and sets x-locale header for downstream route handlers.

How it works:

1. User visits /tr/blog
2. Proxy extracts tr from the first path segment
3. Sets x-locale: tr response header (accessible via headers().get('x-locale'))
4. Route handlers can read this header
5. API client automatically appends ?lang=tr to backend requests

See the i18n documentation for full setup guide.

excludedPaths#

Paths to skip proxy entirely.

blockBrowserApiAccess#

Block direct browser access to API routes.

When enabled, requests with Accept: text/html to /api/* are redirected to /.

responseMappers#

Custom parsers for different backend response formats.

refresh#

Token refresh behaviour — concurrency, proactive renewal, and reuse detection (RFC 9700). All fields are optional; with no refresh config, behaviour matches earlier versions (reactive refresh only).

On a detected reuse — or when access.guestFallbackOnUserRefreshFail is false — the proxy clears every auth cookie and redirects to login (or returns 401 for API routes). It never silently downgrades to a guest session.

validate#

Token validation strategy. By default (mode: 'backend') the proxy validates the token against endpoints.validate on every request. mode: 'local' verifies the JWT in-process, restoring stateless auth and removing the per-request backend roundtrip.

Local mode verifies JWT access tokens. Supply validate.verify for asymmetric algorithms (RS256 / ES256) or JWKS key rotation.

csrf#

CSRF protection configuration.

rateLimit#

Rate limiting configuration.

audit#

Audit logging configuration.

onError#

Global error handler.

beforeAuth#

Hook that runs before auth validation.

afterAuth#

Hook that runs after auth validation.

Full Example#