Text of github.com › auth0 › nextjs-auth0 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

GitHub - auth0/nextjs-auth0: Next.js SDK for signing in with Auth0 · GitHub

Skip to content You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert Branches Tags Open more actions menu Latest commit History 3,386 Commits 3,386 Commits Folders and files Name Name Last commit message Last commit date .github .github docs docs e2e e2e examples examples guides guides mintlify mintlify skills skills src src tests tests .DS_Store .DS_Store .gitignore .gitignore .shiprc .shiprc .version .version AGENTS.md AGENTS.md CHANGELOG.md CHANGELOG.md CODE-OF-CONDUCT.md CODE-OF-CONDUCT.md CONTRIBUTING.md CONTRIBUTING.md EXAMPLES.md EXAMPLES.md LICENSE LICENSE NOTICE NOTICE README.md README.md SECURITY.md SECURITY.md V1_MIGRATION_GUIDE.md V1_MIGRATION_GUIDE.md V2_MIGRATION_GUIDE.md V2_MIGRATION_GUIDE.md V3_MIGRATION_GUIDE.md V3_MIGRATION_GUIDE.md V4_MIGRATION_GUIDE.md V4_MIGRATION_GUIDE.md eslint.config.mjs eslint.config.mjs lefthook.yml lefthook.yml package.json package.json playwright.config.ts playwright.config.ts pnpm-lock.yaml pnpm-lock.yaml pnpm-workspace.yaml pnpm-workspace.yaml prettier.config.mjs prettier.config.mjs tsconfig.base.json tsconfig.base.json tsconfig.json tsconfig.json tsconfig.test.json tsconfig.test.json typedoc.json typedoc.json vitest.config.mts vitest.config.mts Repository files navigation The Auth0 Next.js SDK is a library for implementing user authentication in Next.js applications. 📚 Documentation - 🚀 Getting Started - 💻 API Reference - 💬 Feedback Documentation QuickStart - our guide for adding Auth0 to your Next.js app.

Examples - lots of examples for your different use cases. Anonymous Sessions - enable pre-login identity with access tokens and metadata. Security - Some important security notices that you should check. Docs Site - explore our docs site and learn more about Auth0. Getting Started 1. Install the SDK npm i @auth0/nextjs-auth0 This library requires Node.js 20 LTS and newer LTS versions. 2. Add the environment variables Add the following environment variables to your .env.local file: AUTH0_DOMAIN = AUTH0_CLIENT_ID = AUTH0_CLIENT_SECRET = AUTH0_SECRET = APP_BASE_URL = # optional for dynamic preview environments The AUTH0_DOMAIN , AUTH0_CLIENT_ID , and AUTH0_CLIENT_SECRET can be obtained from the Auth0 Dashboard once you've created an application.

This application must be a Regular Web Application . The AUTH0_SECRET is the key used to encrypt the session and transaction cookies. You can generate a secret using openssl : openssl rand -hex 32 The APP_BASE_URL is the URL that your application is running on. When developing locally, this is most commonly http://localhost:3000 . If you omit it, the SDK will infer the base URL from the incoming request host at runtime.

Important You will need to register the following URLs in your Auth0 Application via the Auth0 Dashboard : Add http://localhost:3000/auth/callback to the list of Allowed Callback URLs Add http://localhost:3000 to the list of Allowed Logout URLs When using dynamic hosts (preview environments), ensure the resulting callback and logout URLs are registered in your Auth0 application. Dynamic base URLs (Preview deployments) For preview environments ( Vercel , Netlify ), you can omit APP_BASE_URL and let the SDK infer the base URL from the incoming request host at runtime.

This keeps dynamic preview URLs working without extra configuration. If you know the base URL at startup (for example, a stable production domain), set appBaseUrl or APP_BASE_URL to a single absolute URL. Comma-separated values are not supported. Because the Host header is untrusted input, Auth0's Allowed Callback URLs are the safety net in this mode: if the inferred host is not registered, Auth0 rejects the authorize request.

Example (dynamic): import { Auth0Client } from "@auth0/nextjs-auth0/server" ; export const auth0 = new Auth0Client ( ) ; Example (static): import { Auth0Client } from "@auth0/nextjs-auth0/server" ; export const auth0 = new Auth0Client ( { appBaseUrl : "https://app.example.com" } ) ; Note When relying on dynamic base URLs in production, the SDK enforces secure cookies. If you explicitly set AUTH0_COOKIE_SECURE=false , session.cookie.secure=false , or transactionCookie.secure=false , the SDK throws InvalidConfigurationError .

3. Create the Auth0 SDK client Create an instance of the Auth0 client. This instance will be imported and used in anywhere you need access to the authentication methods on the server. Add the following contents to a file named lib/auth0.ts : import { Auth0Client } from "@auth0/nextjs-auth0/server" ; export const auth0 = new Auth0Client ( ) ; Note The Auth0Client automatically uses safe defaults to manage authentication cookies.

For advanced use cases, you can customize transaction cookie behavior by providing your own configuration. See Transaction Cookie Configuration for details. 4. Add the authentication middleware Authentication requests in Next.js are intercepted at the network boundary using a middleware or proxy file. Follow the setup below depending on your Next.js version. 🟦 On Next.js 15 Create a middleware.ts file in the root of your project: import type { NextRequest } from "next/server" ; import { auth0 } from "./lib/auth0" ; // Adjust path if your auth0 client is elsewhere export async function middleware ( request : NextRequest ) { return await auth0 . middleware ( request ) ; } export const config = { matcher : [ /* * Match all request paths except for: * - _next/static (static files) * - _next/image (image optimization files) * - favicon.ico, sitemap.xml, robots.txt (metadata files) */ "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)" ] } ; Note If you're using a src/ directory, the middleware.ts file must be created inside the src/ directory. 🟨 On Next.js 16 Next.js 16 introduces a new convention called proxy.ts, replacing middleware.ts.

This change better represents the network interception boundary and unifies request handling for both the Edge and Node runtimes. Create a proxy.ts file in the root of your project (Or rename your existing middleware.ts to proxy.ts): import { auth0 } from "./lib/auth0" ; export async function proxy ( request : Request ) { // Note that proxy uses the standard Request type return await auth0 . middleware ( request ) ; } export const config = { matcher : [ "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)" ] } ; Important Starting with Next.js 16 , the recommended file for handling authentication boundaries is proxy.ts .

You can still continue using middleware.ts for backward compatibility, it will work under the Edge runtime in Next.js 16. However, it is deprecated for the Node runtime and will be removed in a future release. The new proxy layer also executes slightly earlier in the routing pipeline, so make sure your matcher patterns do not conflict with other proxy or middleware routes. Additionally, the Edge runtime now applies stricter header and cookie validation, so avoid setting non-string cookie values or invalid header formats.

Important This broad middleware matcher is essential for rolling sessions and security features. For scenarios when rolling sessions are disabled, see Session Configuration for alternative approaches. You can now begin to authenticate your users by redirecting them to your application's /auth/login route: import { auth0 } from "./lib/auth0" ; // Adjust path if your auth0 client is elsewhere export default async function Home ( ) { const session = await auth0 . getSession ( ) ; if ( ! session ) { return ( < main > < a href = "/auth/login?screen_hint=signup" > Sign up </ a > < a href = "/auth/login" > Log in </ a > </ main > ) ; } return ( < main > < h1 > Welcome, { session . user . name } ! </ h1 > </ main > ) ; } Important A default <Link href="/auth/login"> is safe — the SDK detects the AUTO prefetch header and ret

The rest of this page is on the live site.