Proxy Handler

The createProxyHandler function creates a simple API route handler that proxies requests directly to your backend without the full middleware pipeline.

When to Use#

Use createProxyHandler when you need:

Simple request proxying without token validation
Direct backend access with optional auth
Custom API routes that bypass middleware
Public endpoints that don't need authentication

For full authentication middleware with token refresh and validation, use createAuthProxy instead.

Basic Setup#

TypeScript

Configuration#

ProxyHandlerConfig#

Option	Type	Default	Description
`apiBaseUrl`	`string`	Required	Base URL of your backend API
`userCookieName`	`string`	`"auth_token"`	Cookie name for user auth token
`guestCookieName`	`string`	`"guest_token"`	Cookie name for guest auth token
`skipAuthByDefault`	`boolean`	`false`	Skip auth for all requests by default
`publicEndpoints`	`string[]`	`[]`	Endpoints that never include auth token (glob patterns)
`forwardHeaders`	`string[]`	`["content-type", "accept", ...]`	Headers to forward from client request
`excludeHeaders`	`string[]`	`["host", "connection", "cookie"]`	Headers to exclude from forwarding
`transformRequest`	`(req, headers) => Headers`	-	Custom request transformer
`transformResponse`	`(response) => Response`	-	Custom response transformer

Public Endpoints#

Define endpoints that should never include authentication tokens:

TypeScript

Glob Pattern Support#

* - Matches any characters except /
** - Matches any characters including /
Exact string - Exact match only

Skip Auth Header#

Individual requests can skip auth by sending the X-Skip-Auth header:

TypeScript

Custom Transformers#

Request Transformer#

Modify headers before sending to backend:

TypeScript

Response Transformer#

Modify response before sending to client:

TypeScript

Comparison with createAuthProxy#

Feature	createProxyHandler	createAuthProxy
Token Validation	No	Yes
Token Refresh	No	Yes
Guest Token Creation	No	Yes
CSRF Protection	No	Yes
Rate Limiting	No	Yes
Route Protection	Basic (publicEndpoints)	Full (protectedRoutes, authRoutes)
Custom Transformers	Yes	Limited
Use Case	Simple proxying, public APIs	Full authentication flow

Full Example#

TypeScript

TypeScript#

TypeScript

When to Use#

Use createProxyHandler when you need:

Simple request proxying without token validation

Direct backend access with optional auth

Custom API routes that bypass middleware

Public endpoints that don't need authentication

For full authentication middleware with token refresh and validation, use createAuthProxy instead.

Configuration#

Option	Type	Default	Description
`apiBaseUrl`	`string`	Required	Base URL of your backend API
`userCookieName`	`string`	`"auth_token"`	Cookie name for user auth token
`guestCookieName`	`string`	`"guest_token"`	Cookie name for guest auth token
`skipAuthByDefault`	`boolean`	`false`	Skip auth for all requests by default
`publicEndpoints`	`string[]`	`[]`	Endpoints that never include auth token (glob patterns)
`forwardHeaders`	`string[]`	`["content-type", "accept", ...]`	Headers to forward from client request
`excludeHeaders`	`string[]`	`["host", "connection", "cookie"]`	Headers to exclude from forwarding
`transformRequest`	`(req, headers) => Headers`	-	Custom request transformer
`transformResponse`	`(response) => Response`	-	Custom response transformer

Comparison with createAuthProxy#

Feature	createProxyHandler	createAuthProxy
Token Validation	No	Yes
Token Refresh	No	Yes
Guest Token Creation	No	Yes
CSRF Protection	No	Yes
Rate Limiting	No	Yes
Route Protection	Basic (publicEndpoints)	Full (protectedRoutes, authRoutes)
Custom Transformers	Yes	Limited
Use Case	Simple proxying, public APIs	Full authentication flow