Skip to content
Migrating from NextAuth.js v4? Read our migration guide.
API reference
next-auth

next-auth

If you are looking to migrate from v4, visit the Upgrade Guide (v5).

Installation

npm install next-auth@beta

Environment variable inference

NEXTAUTH_URL and NEXTAUTH_SECRET have been inferred since v4.

Since NextAuth.js v5 can also automatically infer environment variables that are prefixed with AUTH_.

For example AUTH_GITHUB_ID and AUTH_GITHUB_SECRET will be used as the clientId and clientSecret options for the GitHub provider.

💡

The environment variable name inferring has the following format for OAuth providers: AUTH_{PROVIDER}_{ID|SECRET}.

PROVIDER is the uppercase snake case version of the provider’s id, followed by either ID or SECRET respectively.

AUTH_SECRET and AUTH_URL are also aliased for NEXTAUTH_SECRET and NEXTAUTH_URL for consistency.

To add social login to your app, the configuration becomes:

auth.ts
import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"
export const { handlers, auth } = NextAuth({ providers: [ GitHub ] })

And the .env.local file:

.env.local
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...
AUTH_SECRET=...
💡

In production, AUTH_SECRET is a required environment variable - if not set, NextAuth.js will throw an error. See MissingSecretError for more details.

If you need to override the default values for a provider, you can still call it as a function GitHub({...}) as before.

Lazy initialization

You can also initialize NextAuth.js lazily (previously known as advanced intialization), which allows you to access the request context in the configuration in some cases, like Route Handlers, Middleware, API Routes or getServerSideProps. The above example becomes:

auth.ts
import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"
export const { handlers, auth } = NextAuth(req => {
 if (req) {
  console.log(req) // do something with the request
 }
 return { providers: [ GitHub ] }
})
💡

This is useful if you want to customize the configuration based on the request, for example, to add a different provider in staging/dev environments.

AuthError

Base error class for all Auth.js errors. It’s optimized to be printed in the server logs in a nicely formatted way via the logger.error option.

Extends

  • Error

Constructors

new AuthError(message, errorOptions)

new AuthError(message?, errorOptions?): AuthError
Parameters
ParameterType
message?string | ErrorOptions
errorOptions?ErrorOptions
Returns

AuthError

Overrides

Error.constructor

Properties

cause?

optional cause: Record<string, unknown> & {
  err: Error;
};
Type declaration
err?
optional err: Error;
Overrides

Error.cause

message

message: string;
Inherited from

Error.message

name

name: string;
Inherited from

Error.name

stack?

optional stack: string;
Inherited from

Error.stack

type

type: ErrorType;

The error type. Used to identify the error in the logs.

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Optional override for formatting stack traces

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Parameters
ParameterType
errError
stackTracesCallSite[]
Returns

any

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;
Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Create .stack property on a target object

Parameters
ParameterType
targetObjectobject
constructorOpt?Function
Returns

void

Inherited from

Error.captureStackTrace


CredentialsSignin

Can be thrown from the authorize callback of the Credentials provider. When an error occurs during the authorize callback, two things can happen:

  1. The user is redirected to the signin page, with error=CredentialsSignin&code=credentials in the URL. code is configurable.
  2. If you throw this error in a framework that handles form actions server-side, this error is thrown, instead of redirecting the user, so you’ll need to handle.

Extends

Constructors

new CredentialsSignin(message, errorOptions)

new CredentialsSignin(message?, errorOptions?): CredentialsSignin
Parameters
ParameterType
message?string | ErrorOptions
errorOptions?ErrorOptions
Returns

CredentialsSignin

Inherited from

SignInError.constructor

Properties

cause?

optional cause: Record<string, unknown> & {
  err: Error;
};
Type declaration
err?
optional err: Error;
Inherited from

SignInError.cause

code

code: string;

The error code that is set in the code query parameter of the redirect URL.

⚠ NOTE: This property is going to be included in the URL, so make sure it does not hint at sensitive errors.

The full error is always logged on the server, if you need to debug.

Generally, we don’t recommend hinting specifically if the user had either a wrong username or password specifically, try rather something like “Invalid credentials”.

message

message: string;
Inherited from

SignInError.message

name

name: string;
Inherited from

SignInError.name

stack?

optional stack: string;
Inherited from

SignInError.stack

type

type: ErrorType;

The error type. Used to identify the error in the logs.

Inherited from

SignInError.type

kind

static kind: string;
Inherited from

SignInError.kind

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Optional override for formatting stack traces

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Parameters
ParameterType
errError
stackTracesCallSite[]
Returns

any

Inherited from

SignInError.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;
Inherited from

SignInError.stackTraceLimit

type

static type: string;

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Create .stack property on a target object

Parameters
ParameterType
targetObjectobject
constructorOpt?Function
Returns

void

Inherited from

SignInError.captureStackTrace


Account

Usually contains information about the provider being used and also extends TokenSet, which is different tokens returned by OAuth Providers.

Extends

  • Partial<OpenIDTokenEndpointResponse>

Properties

access_token?

optional readonly access_token: string;
Inherited from

Partial.access_token

expires_at?

optional expires_at: number;

Calculated value based on OAuth2TokenEndpointResponse.expires_in.

It is the absolute timestamp (in seconds) when the OAuth2TokenEndpointResponse.access_token expires.

This value can be used for implementing token rotation together with OAuth2TokenEndpointResponse.refresh_token.

See

expires_in?

optional readonly expires_in: number;
Inherited from

Partial.expires_in

id_token?

optional readonly id_token: string;
Inherited from

Partial.id_token

provider

provider: string;

Provider’s id for this account. Eg.: “google”

providerAccountId

providerAccountId: string;

This value depends on the type of the provider being used to create the account.

  • oauth/oidc: The OAuth account’s id, returned from the profile() callback.
  • email: The user’s email address.
  • credentials: id returned from the authorize() callback

refresh_token?

optional readonly refresh_token: string;
Inherited from

Partial.refresh_token

scope?

optional readonly scope: string;
Inherited from

Partial.scope

token_type?

optional readonly token_type: "bearer" | "dpop" | Lowercase<string>;

NOTE: because the value is case insensitive it is always returned lowercased

Inherited from

Partial.token_type

type

type: ProviderType;

Provider’s type for this account

userId?

optional userId: string;

id of the user this account belongs to

See

https://authjs.dev/reference/core/adapters#adapteruser


DefaultSession

Extended by

Properties

expires

expires: string;

user?

optional user: User;

NextAuthConfig

Configure NextAuth.js.

Extends

Properties

adapter?

optional adapter: Adapter;

You can use the adapter option to pass in your database adapter.

Inherited from

Omit.adapter

basePath?

optional basePath: string;

The base path of the Auth.js API endpoints.

Default
"/api/auth" in "next-auth"; "/auth" with all other frameworks
Inherited from

Omit.basePath

callbacks?

optional callbacks: Partial<CallbacksOptions<Profile, Account>> & {
  authorized: (params) => Awaitable<undefined | boolean | Response | NextResponse<unknown>>;
};

Callbacks are asynchronous functions you can use to control what happens when an auth-related action is performed. Callbacks allow you to implement access controls without a database or to integrate with external databases or APIs.

Type declaration
authorized()?
optional authorized: (params) => Awaitable<undefined | boolean | Response | NextResponse<unknown>>;

Invoked when a user needs authorization, using Middleware.

You can override this behavior by returning a NextResponse.

Example
app/auth.ts
async authorized({ request, auth }) {
  const url = request.nextUrl
 
  if(request.method === "POST") {
    const { authToken } = (await request.json()) ?? {}
    // If the request has a valid auth token, it is authorized
    const valid = await validateAuthToken(authToken)
    if(valid) return true
    return NextResponse.json("Invalid auth token", { status: 401 })
  }
 
  // Logged in users are authenticated, otherwise redirect to login page
  return !!auth.user
}
⚠️

If you are returning a redirect response, make sure that the page you are redirecting to is not protected by this callback, otherwise you could end up in an infinite redirect loop.

Parameters
ParameterTypeDescription
paramsObject-
params.authnull | SessionThe authenticated user or token, if any.
params.requestNextRequestThe request to be authorized.
Returns

Awaitable<undefined | boolean | Response | NextResponse<unknown>>

Overrides

Omit.callbacks

cookies?

optional cookies: Partial<CookiesOptions>;

You can override the default cookie names and options for any of the cookies used by Auth.js. You can specify one or more cookies with custom properties and missing options will use the default values defined by Auth.js. If you use this feature, you will likely want to create conditional behavior to support setting different cookies policies in development and production builds, as you will be opting out of the built-in dynamic policy.

  • This is an advanced option. Advanced options are passed the same way as basic options, but may have complex implications or side effects. You should try to avoid using advanced options unless you are very comfortable using them.
Default
{}
Inherited from

Omit.cookies

debug?

optional debug: boolean;

Set debug to true to enable debug messages for authentication and database operations.

Default
false
Inherited from

Omit.debug

events?

optional events: Partial<EventCallbacks>;

Events are asynchronous functions that do not return a response, they are useful for audit logging. You can specify a handler for any of these events below - e.g. for debugging or to create an audit log. The content of the message object varies depending on the flow (e.g. OAuth or Email authentication flow, JWT or database sessions, etc), but typically contains a user object and/or contents of the JSON Web Token and other information relevant to the event.

Default
{}
Inherited from

Omit.events

experimental?

optional experimental: {
  enableWebAuthn: boolean;
};

Use this option to enable experimental features. When enabled, it will print a warning message to the console.

Note

Experimental features are not guaranteed to be stable and may change or be removed without notice. Please use with caution.

Default
{}
enableWebAuthn?
optional enableWebAuthn: boolean;

Enable WebAuthn support.

Default
false
Inherited from

Omit.experimental

jwt?

optional jwt: Partial<JWTOptions>;

JSON Web Tokens are enabled by default if you have not specified an AuthConfig.adapter. JSON Web Tokens are encrypted (JWE) by default. We recommend you keep this behaviour.

Inherited from

Omit.jwt

logger?

optional logger: Partial<LoggerInstance>;

Override any of the logger levels (undefined levels will use the built-in logger), and intercept logs in NextAuth. You can use this option to send NextAuth logs to a third-party logging service.

Example
// /auth.ts
import log from "logging-service"
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  logger: {
    error(code, ...message) {
      log.error(code, message)
    },
    warn(code, ...message) {
      log.warn(code, message)
    },
    debug(code, ...message) {
      log.debug(code, message)
    }
  }
})
Default
console
Inherited from

Omit.logger

pages?

optional pages: Partial<PagesOptions>;

Specify URLs to be used if you want to create custom sign in, sign out and error pages. Pages specified will override the corresponding built-in page.

Default
{}
Example
  pages: {
    signIn: '/auth/signin',
    signOut: '/auth/signout',
    error: '/auth/error',
    verifyRequest: '/auth/verify-request',
    newUser: '/auth/new-user'
  }
Inherited from

Omit.pages

providers

providers: Provider[];

List of authentication providers for signing in (e.g. Google, Facebook, Twitter, GitHub, Email, etc) in any order. This can be one of the built-in providers or an object with a custom provider.

Default
[]
Inherited from

Omit.providers

redirectProxyUrl?

optional redirectProxyUrl: string;

When set, during an OAuth sign-in flow, the redirect_uri of the authorization request will be set based on this value.

This is useful if your OAuth Provider only supports a single redirect_uri or you want to use OAuth on preview URLs (like Vercel), where you don’t know the final deployment URL beforehand.

The url needs to include the full path up to where Auth.js is initialized.

Note

This will auto-enable the state OAuth2Config.checks on the provider.

Example
"https://authjs.example.com/api/auth"

You can also override this individually for each provider.

Example
GitHub({
  ...
  redirectProxyUrl: "https://github.example.com/api/auth"
})
Default

AUTH_REDIRECT_PROXY_URL environment variable

See also: Guide: Securing a Preview Deployment

Inherited from

Omit.redirectProxyUrl

secret?

optional secret: string | string[];

A random string used to hash tokens, sign cookies and generate cryptographic keys.

To generate a random string, you can use the Auth.js CLI: npx auth secret

Note

You can also pass an array of secrets, in which case the first secret that successfully decrypts the JWT will be used. This is useful for rotating secrets without invalidating existing sessions. The newer secret should be added to the start of the array, which will be used for all new sessions.

Inherited from

Omit.secret

session?

optional session: {
  generateSessionToken: () => string;
  maxAge: number;
  strategy: "jwt" | "database";
  updateAge: number;
};

Configure your session like if you want to use JWT or a database, how long until an idle session expires, or to throttle write operations in case you are using a database.

generateSessionToken()?
optional generateSessionToken: () => string;

Generate a custom session token for database-based sessions. By default, a random UUID or string is generated depending on the Node.js version. However, you can specify your own custom string (such as CUID) to be used.

Default

randomUUID or randomBytes.toHex depending on the Node.js version

Returns

string

maxAge?
optional maxAge: number;

Relative time from now in seconds when to expire the session

Default
2592000 // 30 days
strategy?
optional strategy: "jwt" | "database";

Choose how you want to save the user session. The default is "jwt", an encrypted JWT (JWE) in the session cookie.

If you use an adapter however, we default it to "database" instead. You can still force a JWT session by explicitly defining "jwt".

When using "database", the session cookie will only contain a sessionToken value, which is used to look up the session in the database.

Documentation | Adapter | About JSON Web Tokens

updateAge?
optional updateAge: number;

How often the session should be updated in seconds. If set to 0, session is updated every time.

Default
86400 // 1 day
Inherited from

Omit.session

skipCSRFCheck?

optional skipCSRFCheck: typeof skipCSRFCheck;
Inherited from

Omit.skipCSRFCheck

theme?

optional theme: Theme;

Changes the theme of built-in AuthConfig.pages.

Inherited from

Omit.theme

trustHost?

optional trustHost: boolean;

Auth.js relies on the incoming request’s host header to function correctly. For this reason this property needs to be set to true.

Make sure that your deployment platform sets the host header safely.

Official Auth.js-based libraries will attempt to set this value automatically for some deployment platforms (eg.: Vercel) that are known to set the host header safely.

Inherited from

Omit.trustHost

useSecureCookies?

optional useSecureCookies: boolean;

When set to true then all cookies set by NextAuth.js will only be accessible from HTTPS URLs. This option defaults to false on URLs that start with http:// (e.g. http://localhost:3000) for developer convenience. You can manually set this option to false to disable this security feature and allow cookies to be accessible from non-secured URLs (this is not recommended).

  • This is an advanced option. Advanced options are passed the same way as basic options, but may have complex implications or side effects. You should try to avoid using advanced options unless you are very comfortable using them.

The default is false HTTP and true for HTTPS sites.

Inherited from

Omit.useSecureCookies


NextAuthResult

The result of invoking NextAuth, initialized with the NextAuthConfig. It contains methods to set up and interact with NextAuth.js in your Next.js app.

Properties

auth

auth: (...args) => Promise<null | Session> & (...args) => Promise<null | Session> & (...args) => Promise<null | Session> & (...args) => AppRouteHandlerFn;

A universal method to interact with NextAuth.js in your Next.js app. After initializing NextAuth.js in auth.ts, use this method in Middleware, Server Components, Route Handlers (app/), and Edge or Node.js API Routes (pages/).

In Middleware

Adding auth to your Middleware is optional, but recommended to keep the user session alive.

Authentication is done by the callbacks.authorized callback.

Example
middleware.ts
export { auth as middleware } from "./auth"

Alternatively you can wrap your own middleware with auth, where req is extended with auth:

Example
middleware.ts
import { auth } from "./auth"
export default auth((req) => {
  // req.auth
})
// Optionally, don't invoke Middleware on some paths
// Read more: https://nextjs.org/docs/app/building-your-application/routing/middleware#matcher
export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
}

In Server Components

Example
app/page.ts
import { auth } from "../auth"
 
export default async function Page() {
  const { user } = await auth()
  return <p>Hello {user?.name}</p>
}

In Route Handlers

Example
app/api/route.ts
import { auth } from "../../auth"
 
export const POST = auth((req) => {
  // req.auth
})

In Edge API Routes

Example
pages/api/protected.ts
import { auth } from "../../auth"
 
export default auth((req) => {
  // req.auth
})
 
export const config = { runtime: "edge" }

In API Routes

Example
pages/api/protected.ts
import { auth } from "../auth"
import type { NextApiRequest, NextApiResponse } from "next"
 
export default async (req: NextApiRequest, res: NextApiResponse) => {
  const session = await auth(req, res)
  if (session) {
    // Do something with the session
    return res.json("This is protected content.")
  }
  res.status(401).json("You must be signed in.")
}

In getServerSideProps

Example
pages/protected-ssr.ts
import { auth } from "../auth"
 
export const getServerSideProps: GetServerSideProps = async (context) => {
  const session = await auth(context)
 
  if (session) {
    // Do something with the session
    return { props: { session, content: (await res.json()).content } }
  }
 
  return { props: {} }
}

handlers

handlers: AppRouteHandlers;

The NextAuth.js Route Handler methods. These are used to expose an endpoint for OAuth/Email providers, as well as REST API endpoints (such as /api/auth/session) that can be contacted from the client.

After initializing NextAuth.js in auth.ts, re-export these methods.

In app/api/auth/[...nextauth]/route.ts:

app/api/auth/[...nextauth]/route.ts
export { GET, POST } from "../../../../auth"
export const runtime = "edge" // optional

Then auth.ts:

auth.ts
// ...
export const { handlers: { GET, POST }, auth } = NextAuth({...})

signIn()

signIn: <P, R>(provider?, options?, authorizationParams?) => Promise<R extends false ? any : never>;

Sign in with a provider. If no provider is specified, the user will be redirected to the sign in page.

By default, the user is redirected to the current page after signing in. You can override this behavior by setting the redirectTo option.

Example
app/layout.tsx
import { signIn } from "../auth"
 
export default function Layout() {
 return (
  <form action={async () => {
    "use server"
    await signIn("github")
  }}>
   <button>Sign in with GitHub</button>
  </form>
)

If an error occurs during signin, an instance of AuthError will be thrown. You can catch it like this:

app/layout.tsx
import { AuthError } from "next-auth"
import { signIn } from "../auth"
 
export default function Layout() {
 return (
   <form action={async (formData) => {
     "use server"
     try {
       await signIn("credentials", formData)
    } catch(error) {
      if (error instanceof AuthError) // Handle auth errors
      throw error // Rethrow all other errors
    }
   }}>
    <button>Sign in</button>
  </form>
 )
}
Type parameters
Type parameterValue
P extends BuiltInProviderType | string & {}-
R extends booleantrue
Parameters
ParameterTypeDescription
provider?PProvider to sign in to
options?FormData | { redirect: R; redirectTo: string; } & Record<string, any>-
authorizationParams?string | Record<string, string> | URLSearchParams | string[][]-
Returns

Promise<R extends false ? any : never>

signOut()

signOut: <R>(options?) => Promise<R extends false ? any : never>;

Sign out the user. If the session was created using a database strategy, the session will be removed from the database and the related cookie is invalidated. If the session was created using a JWT, the cookie is invalidated.

By default the user is redirected to the current page after signing out. You can override this behavior by setting the redirectTo option.

Example
app/layout.tsx
import { signOut } from "../auth"
 
export default function Layout() {
 return (
  <form action={async () => {
    "use server"
    await signOut()
  }}>
   <button>Sign out</button>
  </form>
)
Type parameters
Type parameterValue
R extends booleantrue
Parameters
ParameterTypeDescription
options?Object-
options.redirect?RIf set to false, the signOut method will return the URL to redirect to instead of redirecting automatically.
options.redirectTo?stringThe URL to redirect to after signing out. By default, the user is redirected to the current page.
Returns

Promise<R extends false ? any : never>

unstable_update()

unstable_update: (data) => Promise<null | Session>;
Parameters
ParameterType
dataPartial<Session | { user: Partial<undefined | User>; }>
Returns

Promise<null | Session>


Profile

The user info returned from your OAuth provider.

See

https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

Indexable

[claim: string]: unknown

Properties

address?

optional address: null | {
  country: null | string;
  formatted: null | string;
  locality: null | string;
  postal_code: null | string;
  region: null | string;
  street_address: null | string;
};

birthdate?

optional birthdate: null | string;

email?

optional email: null | string;

email_verified?

optional email_verified: null | boolean;

family_name?

optional family_name: null | string;

gender?

optional gender: null | string;

given_name?

optional given_name: null | string;

id?

optional id: null | string;

locale?

optional locale: null | string;

middle_name?

optional middle_name: null | string;

name?

optional name: null | string;

nickname?

optional nickname: null | string;

phone_number?

optional phone_number: null | string;

picture?

optional picture: any;

preferred_username?

optional preferred_username: null | string;

profile?

optional profile: null | string;

sub?

optional sub: null | string;

updated_at?

optional updated_at: null | string | number | Date;

website?

optional website: null | string;

zoneinfo?

optional zoneinfo: null | string;

Session

The active session of the logged in user.

Extends

Properties

expires

expires: string;
Inherited from

DefaultSession.expires

user?

optional user: User;
Inherited from

DefaultSession.user


User

The shape of the returned object in the OAuth providers’ profile callback, available in the jwt and session callbacks, or the second parameter of the session callback, when using a database.

Extended by

Properties

email?

optional email: null | string;

id?

optional id: string;

image?

optional image: null | string;

name?

optional name: null | string;

default()

default(config): NextAuthResult

Initialize NextAuth.js.

Parameters

ParameterType
configNextAuthConfig | (request) => NextAuthConfig

Returns

NextAuthResult

Example

auth.ts
import NextAuth from "next-auth"
import GitHub from "@auth/core/providers/github"
 
export const { handlers, auth } = NextAuth({ providers: [GitHub] })

Lazy initialization:

Example

auth.ts
import NextAuth from "next-auth"
import GitHub from "@auth/core/providers/github"
 
export const { handlers, auth } = NextAuth((req) => {
  console.log(req) // do something with the request
  return {
    providers: [GitHub],
  },
})
Auth.js © Balázs Orbán and Team - 2024