Next.js Server SDK Reference

Reference documentation for the Neon Auth Next.js server SDK (@neondatabase/auth/next/server). This package provides server-side authentication for Next.js applications using React Server Components, API routes, middleware, and server actions.

For client-side authentication, see the Client SDK reference. For UI components, see the UI Components reference.

Installation
Install the Neon Auth package in your Next.js project using npm, yarn, pnpm, or bun.
npm install @neondatabase/auth@latest
Environment variables
Configure these environment variables in your .env.local file:
- NEON_AUTH_BASE_URL (required): Your Neon Auth server URL from the Neon Console
- NEON_AUTH_COOKIE_SECRET (required): Secret for signing session cookies (must be 32+ characters for HMAC-SHA256 security)
Generate a secure secret with: openssl rand -base64 32
# Required: Your Neon Auth server URL NEON_AUTH_BASE_URL=https://your-neon-auth-url.neon.tech # Required: Cookie secret for session data signing (32+ characters) NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
createNeonAuth()
createNeonAuth(config)
Creates a unified auth instance that provides all server-side authentication functionality.
Returns an auth object with:
- handler() - Creates API route handlers
- middleware() - Creates Next.js middleware for route protection
- getSession() - Retrieves current session
- All Better Auth server methods (signIn, signUp, signOut, etc.)
Parameters
Parameter Type Required Default
baseUrl string ✓ -
cookies.secret string ✓ -
cookies.sessionDataTtl number 300
cookies.domain string -
cookies.sameSite string strict
logLevel string warn
logger object console (per level)
See Server logging and Upstream fetch errors.
// lib/auth/server.ts import { createNeonAuth } from '@neondatabase/auth/next/server'; export const auth = createNeonAuth({ baseUrl: process.env.NEON_AUTH_BASE_URL!, cookies: { secret: process.env.NEON_AUTH_COOKIE_SECRET!, }, // logLevel: 'silent', });
Server logging
Neon Auth emits structured logs from the API proxy, middleware, and Better Auth server fetch for upstream failures and session issues.
Defaults: logLevel: 'warn' writes error and warn to console. Set logLevel: 'silent' to disable all Neon Auth console output ('silent' ignores any custom logger). Use info or debug for more detail during local troubleshooting.
Custom sink: Pass a partial logger object with error, warn, info, and/or debug methods. Omitted methods still use console. Metadata may include err and detail for observability tools.
auth.middleware() inherits the same resolved logging configuration from createNeonAuth (no per-request reconfiguration).
import { createNeonAuth } from '@neondatabase/auth/next/server'; export const auth = createNeonAuth({ baseUrl: process.env.NEON_AUTH_BASE_URL!, cookies: { secret: process.env.NEON_AUTH_COOKIE_SECRET! }, logLevel: 'debug', logger: { warn(message, meta) { myLogger.warn({ message, ...meta }); }, }, });
logLevel Console output
silent None
error error only
warn (default) error, warn
info error, warn, info
debug all levels
auth.handler()
auth.handler()
Creates GET and POST route handlers for the Neon Auth API proxy.
Create a catch-all route at app/api/auth/[...path]/route.ts. This handles all authentication API calls from your client, including:
- Sign in/sign up requests
- OAuth callbacks
- Session management
- Email verification
- Password reset
Returns
Object with GET and POST Next.js route handlers.
// app/api/auth/[...path]/route.ts import { auth } from '@/lib/auth/server'; export const { GET, POST } = auth.handler();
auth.middleware()
auth.middleware(options)
Creates Next.js middleware for session validation and route protection.
The middleware automatically:
- Validates session cookies on each request
- Provides session data to server components
- Redirects unauthenticated users to the login page
- Refreshes session tokens when needed
Parameters
View parameters
Parameter Type Required Default
loginUrl string /auth/sign-in
Next.js version compatibility
proxy.ts replaces middleware.ts in Next.js 16. On earlier versions, name the file middleware.ts and export default function middleware instead of proxy. The auth logic is identical.
proxy.ts
import { auth } from '@/lib/auth/server'; export default auth.middleware({ loginUrl: '/auth/sign-in' }); export const config = { matcher: [ // Match all paths except static files "/((?!_next/static|_next/image|favicon.ico).*)", ], };
auth.getSession()
auth.getSession()
Retrieves the current session in Server Components, Server Actions, and API Routes.
- Returns cached session if available (fast)
- Automatically refreshes expired tokens
- Returns null if no active session
Server Components that use auth.getSession() must export dynamic = 'force-dynamic' because session data depends on cookies.
Returns
Field Type Description
data Session | null Session with user data, or null if not authenticated
error Error | null Error object if session retrieval failed
// app/dashboard/page.tsx import { auth } from '@/lib/auth/server'; export const dynamic = 'force-dynamic'; export default async function DashboardPage() { const { data: session } = await auth.getSession(); if (!session?.user) { return <div>Not authenticated</div>; } return <h1>Welcome, {session.user.name}</h1>; }

Parameter	Type	Required	Default
`baseUrl`	string	✓	-
`cookies.secret`	string	✓	-
`cookies.sessionDataTtl`	number		300
`cookies.domain`	string		-
`cookies.sameSite`	string		`strict`
`logLevel`	string		`warn`
`logger`	object		`console` (per level)

`logLevel`	Console output
`silent`	None
`error`	`error` only
`warn` (default)	`error`, `warn`
`info`	`error`, `warn`, `info`
`debug`	all levels

Parameter	Type	Required	Default
`loginUrl`	string		`/auth/sign-in`

Field	Type	Description
`data`	Session \| null	Session with user data, or null if not authenticated
`error`	Error \| null	Error object if session retrieval failed

auth.signIn.email(credentials)

Parameters

View parameters

Parameter	Type	Required
`email`	string	✓
`password`	string	✓

'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';

export async function signIn(formData: FormData) {
  const { data, error } = await auth.signIn.email({
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  });

  if (error) return { error: error.message };
  redirect('/dashboard');
}

auth.signIn.social()
auth.signIn.social(options)
Sign in with OAuth provider like Google, GitHub, etc.
Parameters
View parameters
Parameter Type Required
provider string ✓
callbackURL string
const { data, error } = await auth.signIn.social({ provider: 'google', callbackURL: '/dashboard', });
auth.signIn.emailOtp()
auth.signIn.emailOtp(credentials)
Sign in with email OTP (one-time password). First call emailOtp.sendVerificationOtp() to send the code.
Parameters
View parameters
Parameter Type Required
email string ✓
otp string ✓
const { data, error } = await auth.signIn.emailOtp({ email: 'user@example.com', otp: '123456', });
auth.signUp.email()
auth.signUp.email(credentials)
Create a new user account with email and password.
Parameters
View parameters
Parameter Type Required
email string ✓
password string ✓
name string ✓
const { data, error } = await auth.signUp.email({ email: 'user@example.com', password: 'secure-password', name: 'John Doe', });

Parameter	Type	Required
`provider`	string	✓
`callbackURL`	string

auth.signOut()

Sign out the current user. Clears session and authentication tokens.

'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';

export async function signOut() {
  await auth.signOut();
  redirect('/auth/sign-in');
}

auth.updateUser()
auth.updateUser(data)
Update the current user's profile. Password updates require the password reset flow for security.
Parameters
View parameters
Parameter Type Required
name string | undefined
image string | undefined
const { data, error } = await auth.updateUser({ name: 'Jane Doe', image: 'https://example.com/avatar.jpg', });
auth.changePassword()
auth.changePassword(passwords)
Change the current user's password.
Parameters
View parameters
Parameter Type Required
currentPassword string ✓
newPassword string ✓
revokeOtherSessions boolean
const { data, error } = await auth.changePassword({ currentPassword: 'old-password', newPassword: 'new-password', revokeOtherSessions: true, });
auth.sendVerificationEmail()
auth.sendVerificationEmail(options)
Send email verification to the current user.
Parameters
View parameters
Parameter Type Required
callbackURL string
const { data, error } = await auth.sendVerificationEmail({ callbackURL: '/dashboard', });
auth.deleteUser()
auth.deleteUser()
Delete the current user account. This action is irreversible.
const { data, error } = await auth.deleteUser();
auth.emailOtp.sendVerificationOtp()
auth.emailOtp.sendVerificationOtp(options)
Send a one-time password via email. Available when Email OTP authentication is enabled.
Parameters
View parameters
Parameter Type Required
email string ✓
const { data, error } = await auth.emailOtp.sendVerificationOtp({ email: 'user@example.com', });
auth.emailOtp.verifyEmail()
auth.emailOtp.verifyEmail(credentials)
Verify email with OTP code.
Parameters
View parameters
Parameter Type Required
email string ✓
otp string ✓
const { data, error } = await auth.emailOtp.verifyEmail({ email: 'user@example.com', otp: '123456', });
auth.listSessions()
auth.listSessions()
List all active sessions for the current user.
const { data, error } = await auth.listSessions();
auth.revokeSession()
auth.revokeSession(options)
Revoke a specific session by ID.
Parameters
View parameters
Parameter Type Required
sessionId string ✓
const { data, error } = await auth.revokeSession({ sessionId: 'session-id', });
auth.revokeOtherSessions()
auth.revokeOtherSessions()
Revoke all sessions except the current one.
const { data, error } = await auth.revokeOtherSessions();
auth.organization.create()
auth.organization.create(data)
Create a new organization. Available when the organizations plugin is enabled.
Parameters
View parameters
Parameter Type Required
name string ✓
slug string
const { data, error } = await auth.organization.create({ name: 'My Organization', slug: 'my-org', });
auth.organization.list()
auth.organization.list()
List the current user's organizations.
const { data, error } = await auth.organization.list();
auth.organization.inviteMember()
auth.organization.inviteMember(options)
Invite a member to an organization.
Parameters
View parameters
Parameter Type Required
organizationId string ✓
email string ✓
role string
const { data, error } = await auth.organization.inviteMember({ organizationId: 'org-id', email: 'member@example.com', role: 'member', });
auth.admin.listUsers()
auth.admin.listUsers(options)
List all users. Available for users with admin role.
Parameters
View parameters
Parameter Type Required
limit number
offset number
const { data, error } = await auth.admin.listUsers({ limit: 100, offset: 0, });
auth.admin.banUser()
auth.admin.banUser(options)
Ban a user. Available for users with admin role.
Parameters
View parameters
Parameter Type Required
userId string ✓
reason string
const { data, error } = await auth.admin.banUser({ userId: 'user-id', reason: 'Violation of terms', });
auth.admin.setRole()
auth.admin.setRole(options)
Set a user's role. Available for users with admin role.
Parameters
View parameters
Parameter Type Required
userId string ✓
role string ✓
const { data, error } = await auth.admin.setRole({ userId: 'user-id', role: 'admin', });

Parameter	Type	Required
`name`	string \| undefined
`image`	string \| undefined

Parameter	Type	Required
`currentPassword`	string	✓
`newPassword`	string	✓
`revokeOtherSessions`	boolean

Parameter	Type	Required
`callbackURL`	string

Parameter	Type	Required
`sessionId`	string	✓

Parameter	Type	Required
`name`	string	✓
`slug`	string

Parameter	Type	Required
`organizationId`	string	✓
`email`	string	✓
`role`	string

Parameter	Type	Required
`limit`	number
`offset`	number

Parameter	Type	Required
`userId`	string	✓
`reason`	string

Parameter	Type	Required
`userId`	string	✓
`role`	string	✓

Upstream fetch errors

When the SDK cannot reach your Neon Auth server (wrong baseUrl, DNS, TLS, timeout), the API proxy returns a synthetic 502 JSON body with a stable code. Server methods such as auth.signIn.email() surface the same codes on error.code when the failure is transport-related.

Code	Typical cause
`NETWORK_DNS`	Hostname does not resolve
`NETWORK_REFUSED`	Connection refused
`NETWORK_TIMEOUT`	Request timed out
`NETWORK_TLS`	TLS / certificate error
`NETWORK_RESET`	Connection reset
`NETWORK_ABORT`	Request aborted
`NETWORK_ERROR`	Other transport failure

Client-visible messages are generic (for example, “Could not resolve authentication server hostname”). Check server logs (set logLevel: 'debug') for detail and the raw error.

Non-transport failures (unexpected exceptions while handling a response) are re-thrown so Next.js error boundaries still receive the original error. HTTP 4xx upstream responses are logged at info; 5xx at warn.

'use server';

import { auth } from '@/lib/auth/server';

export async function signIn(formData: FormData) {
  const { error } = await auth.signIn.email({
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  });

  if (error?.code === 'NETWORK_DNS') {
    return { error: 'Check NEON_AUTH_BASE_URL in .env.local' };
  }

  if (error) {
    return { error: error.message };
  }
}

Performance features
Session caching
Session data is automatically cached in a signed, HTTP-only cookie to reduce API calls to the Auth Server by 95-99%.
- Default cache TTL: 5 minutes (300 seconds)
- Configurable via cookies.sessionDataTtl
- Automatic expiration based on JWT exp claim
- Synchronous cache clearing on sign-out
- Secure HMAC-SHA256 signing
Request deduplication
Multiple concurrent getSession() calls are automatically deduplicated:
- Single network request for concurrent calls
- 10x faster cold starts
- Reduces server load
// First call: Fetches from Auth Server const { data: session } = await auth.getSession(); // Subsequent calls within TTL: Uses cached data (no API call) const { data: session2 } = await auth.getSession();

Configuration reference

Complete configuration options for createNeonAuth():

Option	Type	Required	Default
`baseUrl`	string	Yes	-
`cookies.secret`	string	Yes	-
`cookies.sessionDataTtl`	number	No	300
`cookies.domain`	string	No	undefined
`cookies.sameSite`	string	No	`strict`
`logLevel`	string	No	`warn`
`logger`	object	No	`console`

baseUrl: Your Neon Auth server URL from the Neon Console
cookies.secret: Secret for HMAC-SHA256 signing (32+ characters)
cookies.sessionDataTtl: Cache TTL in seconds for the signed session_data cookie
cookies.domain: For cross-subdomain sessions (for example, ".example.com")
cookies.sameSite: strict (default), lax, or none. Use lax or none if you embed the app in a third-party iframe or need cookies on cross-site navigations
logLevel: silent, error, warn, info, or debug — see Server logging
logger: Optional custom logger; see Server logging

import { createNeonAuth } from '@neondatabase/auth/next/server';

export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: {
    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
  },
});

Project structure
Recommended file structure for Next.js with Neon Auth:
- app/api/auth/[...path]/route.ts - Auth API handlers
- app/auth/[path]/page.tsx - Auth views (sign-in, sign-up)
- app/dashboard/page.tsx - Protected pages
- lib/auth/server.ts - Server auth instance
- lib/auth/client.ts - Client auth instance
- proxy.ts (Next.js 16+) or middleware.ts (earlier versions) - Route protection
Next.js version compatibility
proxy.ts replaces middleware.ts in Next.js 16. On earlier versions, name the file middleware.ts and export default function middleware instead of proxy. The auth logic is identical.
app/ ├── api/ │ └── auth/ │ └── [...path]/ │ └── route.ts ├── auth/ │ └── [path]/ │ └── page.tsx ├── dashboard/ │ └── page.tsx ├── actions.ts └── layout.tsx lib/ └── auth/ ├── server.ts └── client.ts proxy.ts # or middleware.ts on Next.js < 16 .env.local

Migration from v0.1

If you're upgrading from Neon Auth SDK v0.1, see the migration guide for step-by-step instructions.

Client SDK Reference - Client-side authentication
UI Components Reference - Pre-built auth UI
Next.js quick start - Getting started guide
Migration Guide - Upgrading from v0.1

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.

Next.js Server SDK Reference

Installation

Environment variables

createNeonAuth()

Parameters

Server logging

auth.handler()

Returns

auth.middleware()

Parameters

Next.js version compatibility

auth.getSession()

Returns

auth.signIn.email()

Parameters

auth.signIn.social()

Parameters

auth.signIn.emailOtp()

Parameters

auth.signUp.email()

Parameters

auth.signOut()

auth.updateUser()

Parameters

auth.changePassword()

Parameters

auth.sendVerificationEmail()

Parameters

auth.deleteUser()

auth.emailOtp.sendVerificationOtp()

Parameters

auth.emailOtp.verifyEmail()

Parameters

auth.listSessions()

auth.revokeSession()

Parameters

auth.revokeOtherSessions()

auth.organization.create()

Parameters

auth.organization.list()

auth.organization.inviteMember()

Parameters

auth.admin.listUsers()

Parameters

auth.admin.banUser()

Parameters

auth.admin.setRole()

Parameters

Upstream fetch errors

Performance features

Session caching

Request deduplication

Configuration reference

Project structure

Next.js version compatibility

Migration from v0.1

Related documentation

Need help?