Next.js Pages Router with the Auth0 SDK: v3 patterns vs v4

TL;DR: Pages Router apps use the v3-style SDK surface (handleAuth, withPageAuthRequired). Mixing v4 App Router samples into a Pages Router app is a common agent failure; know which API belongs to which router.

Next.js Pages Router auth

Which SDK version

The @auth0/nextjs-auth0 v4 SDK is App Router first. Pages Router apps historically used v3 (handleAuth, withPageAuthRequired, getSession(req, res)). If the app is on Pages Router, either stay on v3 patterns or migrate the app to App Router first. Do not import v4 App Router helpers into pages/api routes.

v3 setup

pages/api/auth/[...auth0].js:

import { handleAuth } from "@auth0/nextjs-auth0";
export default handleAuth();

This creates /api/auth/login, /api/auth/callback, /api/auth/logout, /api/auth/me.

Protect a page:

import { withPageAuthRequired } from "@auth0/nextjs-auth0";

export const getServerSideProps = withPageAuthRequired();

export default function Protected({ user }) { ... }

Read the session in API routes:

import { getSession } from "@auth0/nextjs-auth0";

export default async function handler(req, res) {
  const session = await getSession(req, res);
  if (!session) return res.status(401).end();
  ...
}

Env vars (v3)

AUTH0_SECRET [your value]
AUTH0_BASE_URL [your app base URL]
AUTH0_ISSUER_BASE_URL YOUR_HOST
AUTH0_CLIENT_ID [your value]
AUTH0_CLIENT_SECRET [your value]

Note the v3 names differ from v4 (AUTH0BASEURL vs APPBASEURL). Copying a v4 env file into a v3 app (or the reverse) silently breaks everything.

Callback registration

Allowed Callback URLs: AUTH0_BASE_URL + /api/auth/callback. Same exact-match rules as everywhere else.

Checklist

• Router version and SDK version agree; v4 helpers are App Router only.
• Env var names match the SDK major version in package.json.

When to use this

• This covers exactly what the title says: Next.js Pages Router with the Auth0 SDK.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with Next.js; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Auth0's Next.js v4 quickstart documents the v4 App Router surface (Auth0Client, middleware, getSession without req/res, APPBASEURL), which supersedes the v3 handleAuth/withPageAuthRequired patterns. The v3-to-v4 migration notes in the SDK changelog document the env var renames. Verified against live docs 2026-09-26.