# Use Managed Better Auth with Next.js (API methods)
:::callout{intent="note" title="Using an AI coding tool?"}
Run `npx neon@latest init` to connect the [Neon MCP server](/guides/postgres-ai-neon-mcp-server) and [Agent Skills](/guides/ai-agents-on-neon-ai-agent-skills) for Managed Better Auth. See [Set up with your AI editor](/guides/auth-index#set-up-with-your-ai-editor) for MCP tools, example prompts, and how skills help wire auth into your app.
:::
This guide shows you how to integrate Managed Better Auth into a [Next.js](https://nextjs.org/) (App Router) project using SDK methods directly. For pre-built UI components, see the [UI components reference](/guides/auth-reference-ui-components) and the [neon-js examples](https://github.com/neondatabase/neon-js/tree/main/examples). Upgrading from v0.1? See the [migration guide](/guides/auth-migrate-from-auth-v0-1).
:::::steps
:::step{title="Enable Auth in your Neon project"}
If you don't have a Neon project yet, create one at [console.neon.tech](https://console.neon.tech/).
Go to the **Auth** page in your project dashboard and click **Enable Auth**, then copy your Auth URL from the Configuration tab.
**Console path:** Project → Branch → Auth → Configuration
Console
:::
::::step{title="Install the Neon SDK"}
Install the Neon SDK into your Next.js app.
:::accordion{title="If you don't have a Next.js project"}
```bash
npx create-next-app@latest my-app --yes
cd my-app
```
:::
```bash
npm install @neondatabase/auth@latest
```
::::
::::step{title="Set up environment variables"}
Create a `.env.local` file in your project root and add your Auth URL and a cookie secret:
:::callout{intent="note"}
Replace the Auth URL with your actual Auth URL from the Neon Console. Generate a secure cookie secret with `openssl rand -base64 32`.
:::
```bash title=".env.local"
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
```
::::
::::step{title="Create auth server instance"}
Create a unified auth instance in `lib/auth/server.ts`. This single instance provides all server-side auth functionality:
- `.handler()` for API routes
- `.middleware()` for route protection
- `.getSession()` and all Better Auth server methods
See the [Next.js Server SDK reference](/guides/auth-reference-nextjs-server) for complete API documentation (logging, cookies, upstream errors).
:::callout{intent="note" title="Server logging"}
The SDK logs structured **`error`** and **`warn`** messages to **`console`** by default (`logLevel: 'warn'`). This helps when the auth proxy or upstream Auth URL is misconfigured. Set **`logLevel: 'silent'`** to disable Managed Better Auth logging, or **`logLevel: 'debug'`** for more detail. See [Server logging](/guides/auth-reference-nextjs-server#server-logging) in the reference.
:::
```typescript title="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!,
// sessionDataTtl: 300, // optional session_data cache TTL in seconds (default: 300)
},
// logLevel: 'silent', // disable Managed Better Auth logging
// logLevel: 'debug', // verbose proxy/upstream logging
});
```
::::
:::step{title="Set up auth API routes"}
Create an API route handler that proxies auth requests. All Managed Better Auth APIs will be routed through this handler. Create a route file inside `/api/auth/[...path]` directory:
```typescript title="app/api/auth/[...path]/route.ts app/api/auth/[...path]/route.ts"
import { auth } from '@/lib/auth/server';
export const { GET, POST } = auth.handler();
```
:::
::::step{title="Add authentication middleware"}
The middleware ensures users are authenticated before accessing protected routes. Create `proxy.ts` file in your project root:
:::callout{intent="note" title="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.
:::
```typescript title="proxy.ts"
import { auth } from '@/lib/auth/server';
export default auth.middleware({
// Redirects unauthenticated users to sign-in page
loginUrl: '/auth/sign-in',
});
export const config = {
matcher: [
// Protected routes requiring authentication
'/account/:path*',
],
};
```
:::callout{intent="note"}
Your Next.js project is now fully configured to use Managed Better Auth. Now, lets proceed with setting up the auth clients.
:::
::::
::::step{title="Configure the auth client"}
Create the auth client in `lib/auth/client.ts` for client-side auth operations (form submissions, hooks, etc.).
:::callout{intent="note"}
The server-side `auth` instance was already created in a previous step. The client is separate and handles browser-side auth operations.
:::
```tsx title="lib/auth/client.ts"
'use client';
import { createAuthClient } from '@neondatabase/auth/next';
export const authClient = createAuthClient();
```
::::
:::step{title="Create Sign up form"}
Lets create a sign-up form and action in `app/auth/sign-up/page.tsx` and `app/auth/sign-up/actions.ts` files respectively using the auth instance we created in previous step
- To create user with email and password, we will use `auth.signUp.email()` with user name, email address, and password
- You can optionally add business logic before invoking the API, for example restrict signups to emails ending with `@my-company.com`
Copy and paste following code in `app/auth/sign-up/actions.ts` file:
```typescript
'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';
export async function signUpWithEmail(
_prevState: { error: string } | null,
formData: FormData
) {
const email = formData.get('email') as string;
if (!email) {
return { error: "Email address must be provided." }
}
// Optionally restrict sign ups based on email address
// if (!email.trim().endsWith("@my-company.com")) {
// return { error: 'Email must be from my-company.com' };
// }
const { error } = await auth.signUp.email({
email,
name: formData.get('name') as string,
password: formData.get('password') as string,
});
if (error) {
return { error: error.message || 'Failed to create account' };
}
redirect('/');
}
```
:::
:::step{title="Create Sign in form"}
Lets create a sign-in form and action in `app/auth/sign-in/page.tsx` and `app/auth/sign-in/actions.ts` files respectively.
- To sign-in the user we will use `auth.signIn.email()` with user's email address and password.
```typescript title="Sign In"
'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';
export async function signInWithEmail(
_prevState: { error: string } | null,
formData: FormData
) {
const { error } = await auth.signIn.email({
email: formData.get('email') as string,
password: formData.get('password') as string,
});
if (error) {
return { error: error.message || 'Failed to sign in. Try again' };
}
redirect('/');
}
```
:::
:::step{title="Create home page"}
In last step, lets create the home page and display authenticated user status:
```typescript title="app/page.tsx"
import { auth } from '@/lib/auth/server';
import Link from 'next/link';
// Server components using auth methods must be rendered dynamically
export const dynamic = 'force-dynamic';
export default async function Home() {
const { data: session } = await auth.getSession();
if (session?.user) {
return (
Logged in as {session.user.name}
);
}
return (
Not logged in
Sign-up
Sign-in
);
}
```
:::
::::step{title="Start your app"}
Start the development server:
Open your browser to [http://localhost:3000](http://localhost:3000/) and test sign-up and sign-in.
:::callout{intent="note" title="Safari users"}
Safari blocks third-party cookies on non-HTTPS connections. Use `npm run dev -- --experimental-https` and open `https://localhost:3000` instead.
:::
```bash
npm run dev
```
::::
:::::
## Available SDK methods
Both `authClient` and `auth` expose similar API methods. Use `authClient` for client components and `auth` for server components, server actions, and API routes.
- [authClient.signUp.email()](/guides/postgres-reference-javascript-sdk#auth-signup) / `auth.signUp.email()` - Create a new user account
- [authClient.signIn.email()](/guides/postgres-reference-javascript-sdk#auth-signinwithpassword) / `auth.signIn.email()` - Sign in with email and password
- [authClient.signOut()](/guides/postgres-reference-javascript-sdk#auth-signout) / `auth.signOut()` - Sign out the current user
- [authClient.getSession()](/guides/postgres-reference-javascript-sdk#auth-getsession) / `auth.getSession()` - Get the current session
- `authClient.updateUser()` / `auth.updateUser()` - Update user details
The `auth` instance also includes `.handler()` for API routes and `.middleware()` for route protection.
## Next steps
- [Next.js Server SDK reference](/guides/auth-reference-nextjs-server) — logging, cookie options, and upstream error codes
- [Auth troubleshooting](/guides/auth-troubleshooting#neon-auth-server-logging-in-the-terminal) — server logging, `NETWORK_*` errors, iframe cookies
- [Add email verification](/guides/auth-guides-email-verification)
- [Branching authentication](/guides/postgres-auth-branching-authentication)
- [More example apps](/guides/auth-index#example-applications) in the **neon-js** `examples/` directory
## Need help?
Join our [Discord Server](https://neon.com/discord) to ask questions or see what others are doing with Neon. For paid plan support options, see [Support](/guides/postgres-introduction-support).
## Related pages
- [Use Managed Better Auth with React (API methods)](./auth-quick-start-react.md)
- [Use Managed Better Auth with TanStack Router](./auth-quick-start-tanstack-router.md)
# Agent Instructions
Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.
:::
::::step{title="Install the Neon SDK"}
Install the Neon SDK into your Next.js app.
:::accordion{title="If you don't have a Next.js project"}
```bash
npx create-next-app@latest my-app --yes
cd my-app
```
:::
```bash
npm install @neondatabase/auth@latest
```
::::
::::step{title="Set up environment variables"}
Create a `.env.local` file in your project root and add your Auth URL and a cookie secret:
:::callout{intent="note"}
Replace the Auth URL with your actual Auth URL from the Neon Console. Generate a secure cookie secret with `openssl rand -base64 32`.
:::
```bash title=".env.local"
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
```
::::
::::step{title="Create auth server instance"}
Create a unified auth instance in `lib/auth/server.ts`. This single instance provides all server-side auth functionality:
- `.handler()` for API routes
- `.middleware()` for route protection
- `.getSession()` and all Better Auth server methods
See the [Next.js Server SDK reference](/guides/auth-reference-nextjs-server) for complete API documentation (logging, cookies, upstream errors).
:::callout{intent="note" title="Server logging"}
The SDK logs structured **`error`** and **`warn`** messages to **`console`** by default (`logLevel: 'warn'`). This helps when the auth proxy or upstream Auth URL is misconfigured. Set **`logLevel: 'silent'`** to disable Managed Better Auth logging, or **`logLevel: 'debug'`** for more detail. See [Server logging](/guides/auth-reference-nextjs-server#server-logging) in the reference.
:::
```typescript title="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!,
// sessionDataTtl: 300, // optional session_data cache TTL in seconds (default: 300)
},
// logLevel: 'silent', // disable Managed Better Auth logging
// logLevel: 'debug', // verbose proxy/upstream logging
});
```
::::
:::step{title="Set up auth API routes"}
Create an API route handler that proxies auth requests. All Managed Better Auth APIs will be routed through this handler. Create a route file inside `/api/auth/[...path]` directory:
```typescript title="app/api/auth/[...path]/route.ts app/api/auth/[...path]/route.ts"
import { auth } from '@/lib/auth/server';
export const { GET, POST } = auth.handler();
```
:::
::::step{title="Add authentication middleware"}
The middleware ensures users are authenticated before accessing protected routes. Create `proxy.ts` file in your project root:
:::callout{intent="note" title="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.
:::
```typescript title="proxy.ts"
import { auth } from '@/lib/auth/server';
export default auth.middleware({
// Redirects unauthenticated users to sign-in page
loginUrl: '/auth/sign-in',
});
export const config = {
matcher: [
// Protected routes requiring authentication
'/account/:path*',
],
};
```
:::callout{intent="note"}
Your Next.js project is now fully configured to use Managed Better Auth. Now, lets proceed with setting up the auth clients.
:::
::::
::::step{title="Configure the auth client"}
Create the auth client in `lib/auth/client.ts` for client-side auth operations (form submissions, hooks, etc.).
:::callout{intent="note"}
The server-side `auth` instance was already created in a previous step. The client is separate and handles browser-side auth operations.
:::
```tsx title="lib/auth/client.ts"
'use client';
import { createAuthClient } from '@neondatabase/auth/next';
export const authClient = createAuthClient();
```
::::
:::step{title="Create Sign up form"}
Lets create a sign-up form and action in `app/auth/sign-up/page.tsx` and `app/auth/sign-up/actions.ts` files respectively using the auth instance we created in previous step
- To create user with email and password, we will use `auth.signUp.email()` with user name, email address, and password
- You can optionally add business logic before invoking the API, for example restrict signups to emails ending with `@my-company.com`
Copy and paste following code in `app/auth/sign-up/actions.ts` file:
```typescript
'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';
export async function signUpWithEmail(
_prevState: { error: string } | null,
formData: FormData
) {
const email = formData.get('email') as string;
if (!email) {
return { error: "Email address must be provided." }
}
// Optionally restrict sign ups based on email address
// if (!email.trim().endsWith("@my-company.com")) {
// return { error: 'Email must be from my-company.com' };
// }
const { error } = await auth.signUp.email({
email,
name: formData.get('name') as string,
password: formData.get('password') as string,
});
if (error) {
return { error: error.message || 'Failed to create account' };
}
redirect('/');
}
```
:::
:::step{title="Create Sign in form"}
Lets create a sign-in form and action in `app/auth/sign-in/page.tsx` and `app/auth/sign-in/actions.ts` files respectively.
- To sign-in the user we will use `auth.signIn.email()` with user's email address and password.
```typescript title="Sign In"
'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';
export async function signInWithEmail(
_prevState: { error: string } | null,
formData: FormData
) {
const { error } = await auth.signIn.email({
email: formData.get('email') as string,
password: formData.get('password') as string,
});
if (error) {
return { error: error.message || 'Failed to sign in. Try again' };
}
redirect('/');
}
```
:::
:::step{title="Create home page"}
In last step, lets create the home page and display authenticated user status:
```typescript title="app/page.tsx"
import { auth } from '@/lib/auth/server';
import Link from 'next/link';
// Server components using auth methods must be rendered dynamically
export const dynamic = 'force-dynamic';
export default async function Home() {
const { data: session } = await auth.getSession();
if (session?.user) {
return (