Documentation Index
Fetch the complete documentation index at: https://mintlify.com/auth0/nextjs-auth0/llms.txt
Use this file to discover all available pages before exploring further.
This guide will help you migrate from 0.x to 1.x of the Auth0 Next.js SDK.
If you only use environment variables to configure the SDK, you don’t need to create an instance of the SDK. You can use the named exports (handleAuth, getSession) directly from @auth0/nextjs-auth0 and they will lazily create an instance of the SDK for you, and configure it using environment variables.
Config Changes
If you still want to create the SDK instance yourself, note that the configuration options have changed as follows:
Breaking Changes
domain is now issuerBaseURL and should be a fully qualified URLclientId is now clientIDredirectUri is now routes.callback and is a relative path, the full URL is constructed using baseURLpostLogoutRedirectUri is now routes.postLogoutRedirect and can be a relative path, the full URL is constructed using baseURL if no host is providedscope and audience are optional and should be passed to authorizationParamssession.cookieSecret is now secretsession.cookieName is now session.namesession.cookieSameSite is now session.cookie.sameSitesession.cookieLifetime is now session.rollingDuration and defaults to 24 hrs rolling and 7 days absolutesession.cookiePath is now session.cookie.path and defaults to '/'session.cookieDomain is now session.cookie.domainsession.storeIdToken, session.storeAccessToken, session.storeRefreshToken are no longer options. All tokens are stored by default, to remove anything from the session see the afterCallback option in handleCallbackoidcClient.httpTimeout is now httpTimeout and defaults to 5000 msoidcClient.clockTolerance is now clockTolerance defined in secs and defaults to 60 secs
import { initAuth0 } from "@auth0/nextjs-auth0"
export default initAuth0({
domain: "my-tenant.auth0.com",
clientId: "MY_CLIENT_ID",
clientSecret: "MY_CLIENT_SECRET",
scope: "openid profile",
audience: "MY_AUDIENCE",
redirectUri: "http://localhost:3000/api/callback",
postLogoutRedirectUri: "http://localhost:3000/",
session: {
cookieSecret: "some_very_long_secret_string",
cookieLifetime: 60 * 60 * 8,
storeIdToken: false,
storeRefreshToken: false,
storeAccessToken: false,
},
oidcClient: {
clockTolerance: 10000,
httpTimeout: 2500,
},
})
import { initAuth0 } from "@auth0/nextjs-auth0"
export default initAuth0({
baseURL: "http://localhost:3000",
issuerBaseURL: "https://my-tenant.auth0.com",
clientID: "MY_CLIENT_ID",
clientSecret: "MY_CLIENT_SECRET",
secret: "some_very_long_secret_string",
clockTolerance: 60,
httpTimeout: 5000,
authorizationParams: {
scope: "openid profile email",
audience: "MY_AUDIENCE",
},
routes: {
callback: "/api/callback",
postLogoutRedirect: "/",
},
session: {
rollingDuration: 60 * 60 * 24,
absoluteDuration: 60 * 60 * 24 * 7,
},
})
getSession
getSession now requires a response as well as a request argument (any updates you make to the session object will now be persisted).
// pages/api/shows.js
import auth0 from "../../lib/auth0"
export default function shows(req, res) {
const session = auth0.getSession(req)
// ...
}
// pages/api/shows.js
import auth0 from "../../lib/auth0"
export default function shows(req, res) {
const session = auth0.getSession(req, res) // Note: the extra argument
// ...
}
getAccessToken
tokenCache has been removed in favor of a single getAccessToken method.
// pages/api/shows.js
import auth0 from "../../lib/auth0"
export default async function shows(req, res) {
const tokenCache = auth0.tokenCache(req, res)
const { accessToken } = await tokenCache.getAccessToken({
scopes: ["read:shows"],
})
// ...
}
// pages/api/shows.js
import auth0 from "../../lib/auth0"
export default async function shows(req, res) {
const { accessToken } = await auth0.getAccessToken(req, res, {
scopes: ["read:shows"],
})
// ...
}
handleLogin
Breaking Changes
authParams is now authorizationParamsredirectTo is now returnTo
// pages/api/login.js
import auth0 from "../../utils/auth0"
export default async function login(req, res) {
try {
await auth0.handleLogin(req, res, {
authParams: {
login_hint: "foo@acme.com",
ui_locales: "nl",
scope: "some other scope",
foo: "bar",
},
redirectTo: "/custom-url",
})
} catch (error) {
console.error(error)
res.status(error.status || 500).end(error.message)
}
}
// pages/api/login.js
import auth0 from "../../utils/auth0"
export default async function login(req, res) {
try {
await auth0.handleLogin(req, res, {
authorizationParams: {
login_hint: "foo@acme.com",
ui_locales: "nl",
scope: "some other scope",
foo: "bar",
},
returnTo: "/custom-url",
})
} catch (error) {
console.error(error)
res.status(error.status || 500).end(error.message)
}
}
handleLogout
redirectTo is now returnTo
// pages/api/logout.js
import auth0 from "../../utils/auth0"
export default async function logout(req, res) {
try {
await auth0.handleLogout(req, res, {
redirectTo: "/custom-url",
})
} catch (error) {
console.error(error)
res.status(error.status || 500).end(error.message)
}
}
// pages/api/logout.js
import auth0 from "../../utils/auth0"
export default async function logout(req, res) {
try {
await auth0.handleLogout(req, res, {
returnTo: "/custom-url",
})
} catch (error) {
console.error(error)
res.status(error.status || 500).end(error.message)
}
}
handleCallback
onUserLoaded is now afterCallback
// pages/api/callback.js
import auth0 from "../../utils/auth0"
export default async function callback(req, res) {
try {
await auth0.handleCallback(req, res, {
async onUserLoaded(req, res, session, state) {
return session
},
})
} catch (error) {
console.error(error)
res.status(error.status || 500).end(error.message)
}
}
// pages/api/callback.js
import auth0 from "../../utils/auth0"
export default async function callback(req, res) {
try {
await auth0.handleCallback(req, res, {
async afterCallback(req, res, session, state) {
return session
},
})
} catch (error) {
console.error(error)
res.status(error.status || 500).end(error.message)
}
}
