API Reference
Complete API reference for all next-api-layer exports.
Server-Side#
createAuthProxy#
Creates a Next.js proxy for handling authentication.
Parameters:
config- AuthProxyConfig object
Returns:
- Next.js proxy function
Example:
createApiClient#
Creates a server-side API client for making authenticated requests.
Parameters:
config- ApiClientConfig object
Returns:
- ApiClient instance with request methods
Methods:
| Method | Signature | Description |
|---|---|---|
get | get(endpoint, options?) | GET request |
post | post(endpoint, body?, options?) | POST request |
put | put(endpoint, body?, options?) | PUT request |
patch | patch(endpoint, body?, options?) | PATCH request |
delete | delete(endpoint, options?) | DELETE request |
Example:
getServerUser#
Fetches the current user on the server side. First checks x-auth-user header (set by proxy) for zero-latency access, falls back to backend validation only if needed.
Parameters:
| Option | Type | Default | Description |
|---|---|---|---|
userCookie | string | "userAuthToken" | Name of the user token cookie |
guestCookie | string | "guestAuthToken" | Name of the guest token cookie |
apiBaseUrl | string | process.env.API_BASE_URL | Base URL for API requests |
validateEndpoint | string | "auth/me" | Endpoint to validate token |
skipHeader | boolean | false | Skip header check and always fetch from backend |
isGuestFn | (user) => boolean | checks token_type | Function to check if user is a guest |
parseResponse | (response) => TUser | extracts from data/user | Function to parse API response |
Returns: Promise<ServerUserResult<TUser>>
Example:
isAuthenticatedServer#
Lightweight check if user is authenticated. Only checks for cookie presence, doesn't validate with backend.
Parameters:
userCookie- Cookie name to check (default:"userAuthToken")
Returns: Promise<boolean>
Example:
getServerToken#
Get the auth token directly in Server Components.
Parameters:
userCookie- User cookie name (default:"userAuthToken")guestCookie- Guest cookie name (default:"guestAuthToken")
Returns: Promise<string | null>
Example:
Utilities#
getClientIp#
Resolve the real client IP behind proxies and CDNs (Cloudflare, Akamai, nginx).
Used internally by the rate limiter and audit logger, and exported for reuse in
custom keyFn implementations or your own middleware.
Parameters:
req- TheNextRequest(or any object with aheadersmap)headerPriority?- Ordered list of headers to check (defaults toDEFAULT_IP_HEADERS)
Returns: string - The resolved client IP, or 'unknown' if none found.
For x-forwarded-for, the first (left-most) address — the original client — is used.
DEFAULT_IP_HEADERS is the default priority list:
isPrefetchRequest#
Detect whether a request is a Next.js <Link> prefetch. Used by the rate
limiter (via skipPrefetch) and exported for custom logic.
Parameters:
req- TheNextRequest(or any object with aheadersmap)
Returns: boolean - true when the request carries a prefetch hint
(next-router-prefetch, sec-purpose, purpose / x-purpose, or x-moz).
Client-Side#
AuthProvider#
React context provider for authentication state.
Props:
| Prop | Type | Default | Description |
|---|---|---|---|
userEndpoint | string | /api/auth/me | Endpoint to fetch user data |
loginEndpoint | string | /api/auth/login | Endpoint for login requests |
registerEndpoint | string | /api/auth/register | Endpoint for registration |
logoutEndpoint | string | /api/auth/logout | Endpoint for logout |
logoutRedirect | string | - | Redirect path after logout |
swrConfig | SWRConfiguration | {} | SWR options |
isGuestFn | (user) => boolean | checks token_type | Function to check if user is guest |
parseResponse | (res) => TUser | extracts from data/user | Function to parse API response |
onLogin | (user) => void | - | Callback on successful login |
onLogout | () => void | - | Callback on logout |
onError | (error) => void | - | Error callback |
initialUser | TUser | - | Initial user from SSR |
useAuth#
Hook to access authentication state and actions.
Returns:
| Property | Type | Description |
|---|---|---|
user | TUser | null | Current user |
isAuthenticated | boolean | Is authenticated (not guest) |
isGuest | boolean | Is guest session |
isLoading | boolean | Loading state |
error | Error | null | Auth error |
login | (credentials) => Promise<AuthResult> | Login with credentials |
register | (data) => Promise<AuthResult> | Register new user |
logout | () => Promise<void> | Log out |
refresh | () => Promise<void> | Refresh user data |
mutate | () => Promise<void> | Revalidate user (SWR mutate) |
Configuration Types#
AuthProxyConfig#
ApiClientConfig#
CsrfConfig#
RateLimitConfig#
AuditConfig#
Response Types#
ApiResponse#
Standard API response format.
AuthResult#
Result of authentication validation.
TokenInfo#
Token validation result.