NextAuth.js FAQ & Answers

86400 * 180 seconds (which equals 6 months)

PEM-encoded, unencrypted PKCS#8

https://bal.so/apple-gen-secret

15 minutes

Yes, PKCE is enabled by default for the Apple provider (checks: ["pkce"]).

Apple requires the client secret to be a JWT (JSON Web Token).

{ alg: 'ES256', kid: keyId, typ: 'JWT' }

null (Apple doesn't provide profile pictures through their authentication flow)

Service ID. The clientId should be set to your Apple Service ID, not your App ID.

ES256

https://appleid.apple.com/auth/authorize

transfer_sub (a string value representing the transfer identifier used to migrate users)

oidc

No, Apple doesn't allow you to use localhost in domains or subdomains.

sub (subject claim)

https://appleid.apple.com/.well-known/openid-configuration

Yes, developers must register their outbound email domains with the Private Relay service, and all registered domains must create Sender Policy Framework (SPF) DNS TXT records.

6 months (180 days). Apple doesn't accept client secret JWTs with an expiration date more than six months after the creation date.

is_private_email (a String or Boolean value: "true"/"false" or true/false)

npx auth add apple

import AppleProvider from "next-auth/providers/apple"

AUTH_ (for example, AUTH_APPLE_ID instead of APPLE_ID)

teamId (Team ID), keyId (Key ID), privateKey (contents of .p8 file), and clientId (Service ID)

__Secure-next-auth.pkce.code_verifier

"name email"

With form_post, parameters are sent back in the body of the POST request. With query, parameters are in the URL. However, Apple requires form_post when requesting name or email scope, and query mode causes scope not to work.

https://appleid.apple.com/auth/token

AUTH_APPLE_ID and AUTH_APPLE_SECRET (it adds them to your .env file)

form_post. The response_mode must be form_post when name or email scope is requested.

Always true (or the string "true"), because Apple servers only return verified email addresses.

Setting pkceCodeVerifier cookie with sameSite: 'none' and secure: true in the cookies configuration

@privaterelay.appleid.com

Yes, Apple requires all sites to run HTTPS, including local development instances.

nonce_supported. If this claim returns true, you should treat nonce as mandatory and fail the transaction; otherwise, you can proceed treating the nonce as optional.

Your Client ID (Service ID)

60 days after the app transfer is complete

Your Apple Team ID

Only the first time the user consents to the app. Apple only returns the name on the first sign in.

An Integer value (0/Unsupported, 1/Unknown, 2/LikelyReal) that indicates whether the user appears to be a real person. It's only present on iOS 14+, macOS 11+, watchOS 7+, tvOS 14+, and is NOT available for web-based apps.

https://appleid.apple.com

The Resend API endpoint is https://api.resend.com/emails.

The default maximum rate limit is 2 requests per second. After that, you'll hit the rate limit and receive a 429 response error code. This number can be increased for trusted senders upon request.

The sendVerificationRequest function receives: identifier (email address), url (verification link), provider (containing server and from properties), theme (UI theme options), token (verification token), and expires (expiration date).

Port 587 should use secure: false and starts unencrypted, then upgrades via STARTTLS. Most modern SMTP servers support STARTTLS automatically unless explicitly disabled with ignoreTLS: true.

Postmark requires that you keep your bounce rate below 10% and spam complaint rate below 0.1%.

The SendGrid provider automatically detects the AUTH_SENDGRID_KEY environment variable. If you name your environment variable this way, the provider will pick it up automatically.

The batch endpoint accepts up to 500 messages per API call. The total payload size, including attachments, is limited to 50 MB for the Batch Email API. For the regular Email API, the size limit is 10 MB including attachments.

The default colors are: background: '#f9f9f9', text: '#444', mainBackground: '#fff', buttonBackground: brandColor, buttonBorder: brandColor, and buttonText: theme.buttonText || '#fff'.

SendGrid has a default rate limit of 600 requests per minute for most API endpoints. When exceeded, the API responds with an HTTP 429 status code and a Retry-After header.

The maxAge parameter is measured in seconds. The default value is 24 * 60 * 60 (86,400 seconds = 24 hours). You can configure it like: maxAge: 24 * 60 * 60 // How long email links are valid for (default 24h)

By default, NextAuth.js normalizes email addresses by treating them as case-insensitive (technically not compliant to RFC 2821 spec) and removes any secondary email addresses passed in as comma-separated lists. The documentation states this approach 'causes more problems than it solves' when strictly following RFC 2821.

The default expiration time is 24 hours (86,400 seconds). The documentation states: 'By default, the email verification token in NextAuth.js is valid for 24 hours.'

No, NextAuth.js does not include nodemailer as a dependency. You must install it separately by running npm install nodemailer or yarn add nodemailer if you want to use the Nodemailer provider.

The default method uses randomBytes(32).toString('hex'), generating a 32-byte random token converted to hexadecimal format.

If requireTLS is true and secure is false, it forces Nodemailer to use STARTTLS even if the server does not advertise support for it.

The total size of your email, including attachments, must be less than 30MB. The total number of recipients must be no more than 1000.

Yes, you can apply your own normalization via the normalizeIdentifier method on the EmailProvider. The function signature is: normalizeIdentifier: (identifier) => string. This allows you to customize email validation and normalization logic.

Use the format 'Your App Name <[email protected]>'. Example: Resend({ from: 'Your App Name <[email protected]>' })

The Postmark provider automatically detects the AUTH_POSTMARK_KEY environment variable. If you name your environment variable this way, the provider will pick it up automatically.

Port 465 should use secure: true. The documentation states: 'The secure option should be set to true only for port 465. For every other port, it should be false.'

The default subject line is Sign in to ${host}, where ${host} is dynamically replaced with the hostname extracted from the sign-in URL.

The default brand color is #346df1 if not specified in the theme configuration.

Postmark uses the X-Postmark-Server-Token header for authentication and authorization.

The required fields are: identifier (email address), token (unique verification token), expires (expiration timestamp), and a composite unique constraint on [identifier, token]. Timestamps createdAt and updatedAt are also typically included.

Your complaint rate must be lower than 0.08% and your bounce rate must be lower than 4%.

SendGrid offers a free tier which allows sending up to 100 emails per day.

The signIn() callback is triggered twice: first when the user makes a Verification Request (before they are sent an email), and again after they activate the link in the sign-in email.

The Postmark API endpoint for sending emails is https://api.postmarkapp.com/email.

Auth.js has built-in HTTP Email providers for Resend, SendGrid, and Postmark. These providers make it easy to integrate these services for passwordless magic link authentication.

Resend's batch API can send up to 100 emails in a single request.

The SendGrid API endpoint is https://api.sendgrid.com (example: https://api.sendgrid.com/v3/templates).

A user account will not be created until the first time they verify their email address by clicking the link in the email. The documentation states: 'A user account (an entry in the Users table) will not be created until the first time they verify their email address.'

Yes, a database adapter is required. The email provider cannot be used without a database because verification tokens need to be stored. As the documentation states: 'The email provider requires a database, it cannot be used without one.'

If ignoreTLS is true and secure is false, TLS will not be used (either to connect, or as a STARTTLS connection upgrade command). This disables encryption entirely.

Resend uses Bearer token authentication with the apiKey in the Authorization header (format: Authorization: Bearer YOUR_API_KEY).

For SMTP, Postmark recommends limiting the total number of connections to 10 concurrent connections per IP. Connections can be reused, and more than one message can be submitted within the same connection.

The connection string format is: smtp://username:[email protected]:587. For example: EMAIL_SERVER=smtp://username:[email protected]:587

The Resend provider automatically detects the AUTH_RESEND_KEY environment variable. If you name your environment variable this way, the provider will pick it up automatically without needing to pass it manually.

You can set theme.colorScheme to 'auto' (follow preferred system theme), 'dark' (force dark mode), or 'light' (force light mode).

You can configure: signIn (custom sign-in page), signOut (sign-out page), error (error page), verifyRequest (check email message page), and newUser (new user page). Example: pages: { signIn: '/auth/signin', verifyRequest: '/auth/verify-request', error: '/auth/error' }

Adapters must return null when a record is not found (e.g., getUser, getUserByAccount, getAuthenticator). Adapters must throw an error when an operation fails (e.g., updateAuthenticatorCounter fails, createAuthenticator fails).

linkAccount accepts an account parameter containing the account information to be linked to a user. In modern versions, it accepts an object instead of multiple individual parameters.

The authenticator methods (createAuthenticator, getAuthenticator, listAuthenticatorsByUserId, updateAuthenticatorCounter) are optional and only needed for WebAuthn authentication flows.

Use the JSDoc comment: /** @return { import("next-auth/adapters").Adapter } */ above your adapter function to get helpful editor hints and auto-completion.

The function is called runBasicTests and it runs the most basic tests that all adapters should conform to and pass.

createVerificationToken returns Awaitable<undefined | null | VerificationToken>.

createVerificationToken is optional. It's only needed when using email-based authentication flows.

The created_at/createdAt and updated_at/updatedAt fields are removed from all Models in NextAuth version 4.

1. createAuthenticator - creates a new authenticator, 2) getAuthenticator - retrieves an authenticator by credentialID, 3) listAuthenticatorsByUserId - returns all authenticators for a user, 4) updateAuthenticatorCounter - updates the authenticator's counter on each login.

getSessionAndUser returns Awaitable<{ session: AdapterSession; user: AdapterUser } | null>. It returns both the session and user from the database in one go, or null if either could not be retrieved.

You can extend an existing adapter by spreading it and adding your custom methods: adapter: { ...PrismaAdapter(prisma), createUser() { /* custom implementation */ } }

If an authenticator is not found, the adapter must return null.

The Session model in NextAuth.js v4 has the following fields: id, userId, expires, and sessionToken.

The code can be found in basic-tests.ts in the nextauthjs/adapters repository, and specific implementations can be found in the /tests subdirectory.

updateSession returns Awaitable<undefined | null | AdapterSession>. It should return the updated session object after successfully updating it in the database.

Import the Adapter type from "next-auth/adapters" using: import type { Adapter } from "next-auth/adapters"

useVerificationToken returns the verification token from the database and deletes it so it can only be used once.

unlinkAccount accepts an object with { providerAccountId, provider } parameters.

getUserByAccount accepts an object with two parameters: { providerAccountId, provider }. It uses the provider id and the id of the user for a specific account to get the user.

The function pattern allows you to instantiate a client/ORM with the provided config parameter, making it easier to configure database connections, reuse existing client instances, and support multiple database configurations.

Yes. The token provided to createVerificationToken is already hashed, so nothing has to be done - simply write it to your database.

No. As of v4, NextAuth.js no longer ships with an adapter included by default. If you would like to persist any information, you need to install one of the many available adapters yourself.

createUser returns Awaitable<AdapterUser>. The method signature is: async createUser(user: Omit<AdapterUser, 'id'>): Promise<AdapterUser>

getUserByEmail returns null when no user is found. The return type is Awaitable<AdapterUser | null>.

1. Plain object pattern: define adapter methods directly in an object. 2) Function pattern (recommended): a function that accepts config parameters and returns an adapter object. The function pattern is what official adapters use.

Awaitable is a type used in NextAuth to indicate that methods are asynchronous and can return either a Promise or the value directly. It's used throughout adapter method signatures to support both async and sync implementations.

AdapterUser requires: id: string, email: string, and emailVerified: Date | null

NextAuth.js currently requires 10 different methods to comprehensively cover each part of the sign in flow, each providing a different part for storing session and account details and getting those details.

If a user is not found, listAuthenticatorsByUserId should still return an empty array. If the retrieval fails for some other reason, the adapter must throw an error.

If an account is not found, the adapter must return null. The return type is Awaitable<AdapterUser | null>.

The VerificationToken interface contains: { identifier: string, expires: Date, token: string }

If any of the methods are not implemented, but are called by Auth.js, an error will be shown to the user and the operation will fail.

The adapter method getSession was renamed to getSessionAndUser in NextAuth v4.

The User id TypeScript type is hard-coded to string in NextAuth.

The methods required for all sign in flows are: createUser, getUser, and getUserByEmail.

For NextAuth v4 compatibility, use adapters with the @next-auth/ prefix (e.g., @next-auth/prisma-adapter, @next-auth/mongodb-adapter). The newer @auth/* adapters are not compatible with the current stable version of next-auth (v4.22.1).

deleteSession returns Awaitable<undefined | null | AdapterSession>. It is preferred that this method also returns the session that is being deleted for logging purposes.

AdapterSession contains: { sessionToken: string, userId: string, expires: Date }

The emailVerified field indicates whether the user has verified their email address via an Email provider. It is null if the user has not signed in with the Email provider yet, or contains the date of the first successful signin.

No. The getToken() helper method can only be used server side.

The update() method triggers a jwt callback with the trigger: 'update' option. You can use this to update the session object on the server.

Encrypted (JWE). By default tokens are not signed but are encrypted. JWT tokens are encrypted by default, not just signed.

You need prompt: 'consent', access_type: 'offline', and response_type: 'code' in the authorization.params configuration.

Yes, NEXTAUTH_SECRET is a required environment variable in production. If not set, NextAuth.js will throw a MissingSecretError: 'Please define a secret in production.'

86400 seconds (24 hours). This is calculated as 24 * 60 * 60 seconds.

__Secure-next-auth.session-token. The __Secure- prefix is used when NEXTAUTH_URL starts with https://.

NextAuth.js implements cookie chunking. If the session exceeds the limit, it creates additional cookies with the suffix .{number}, then merges them together when reading the value.

Yes. NextAuth.js sessions are rotating/rolling, meaning if the user is interacting with the site, the session won't expire.

Yes. NextAuth.js supports PKCE through the 'checks' configuration option. Set checks: ['pkce', 'state'] in your OAuth provider configuration to enable it.

A256CBC-HS512 (AES-256-CBC with HMAC-SHA512). The JWT issued by Auth.js is encrypted by default using the A256CBC-HS512 algorithm (JWE).

It returns the raw encrypted JWE (JSON Web Encryption) string without decrypting or verifying it. Without raw: true, it returns the decrypted token payload.

No. NextAuth.js does not currently handle Access Token rotation for OAuth providers automatically, however you can implement it using jwt and session callbacks.

Only if NEXTAUTH_SECRET is not set as an environment variable. If you don't have NEXTAUTH_SECRET set, you will have to pass your secret as the 'secret' parameter to getToken().

No. Google only provides a refresh token to an application the first time a user signs in. To force Google to re-issue a refresh token, the user needs to remove the application from their account at https://myaccount.google.com/permissions.

Set allowDangerousEmailAccountLinking: true in your provider configuration. This should only be used with providers you trust to verify email addresses.

It defaults to session.maxAge, which is 2592000 seconds (30 days). The value is 60 * 60 * 24 * 30 seconds.

Override authorization.params.scope in your provider configuration. For example: authorization: { params: { scope: 'openid email profile offline_access' } }

The session is updated every time. However, this option is ignored if using JSON Web Tokens (only applies to database sessions).

Yes. The account.expires_at field is automatically calculated and available during first-time login in the jwt callback, based on the expires_in value from the OAuth provider.

Yes. The getToken() helper can read and decode tokens passed from the Authorization: 'Bearer token' HTTP header. If the cookie is not found, it looks for a bearer token in the authorization header.

Database session is the default. If you use an adapter, NextAuth.js defaults the session strategy to 'database' instead of 'jwt'.

3936 bytes (4096 - 160 bytes). The ALLOWED_COOKIE_SIZE is 4096 bytes with an ESTIMATED_EMPTY_COOKIE_SIZE of 160 bytes.

Email addresses in OAuth accounts aren't necessarily verified. A bad actor could create an OAuth account using someone else's email and gain access to their existing account if automatic linking is enabled.

The jwt callback is invoked by requests to /api/auth/signin, /api/auth/session and calls to getSession(), getServerSession(), useSession() (only when using JWT sessions). It's called whenever a JWT is created (at sign in) or updated (whenever a session is accessed).

JWT is the default session strategy. JSON Web Tokens are enabled by default if you have not specified an adapter.

4096 bytes per cookie. This is a browser limitation - cookies have a limit of around 4096 bytes, and if a value exceeds it, the cookie won't be created.

No. Automatic account linking on sign in is not secure between arbitrary providers and is disabled by default.

A256GCM (AES-256 in Galois/Counter Mode). Since v4, all JWT tokens are encrypted by default with A256GCM.

Refresh tokens are usually only usable once. After a successful refresh, the refresh_token is invalidated and cannot be used again. NextAuth.js does not handle concurrent refresh token requests properly, which can cause race conditions.

2592000 seconds (30 days). This is calculated as 30 * 24 * 60 * 60 seconds.

NextAuth.js supports OAuth 1.0, 1.0A, 2.0 and OpenID Connect, with built-in support for most popular sign-in services.

The 'offline_access' scope. For example, with Okta: authorization: { params: { scope: 'openid email profile offline_access' } }. Note: Google uses access_type: 'offline' instead.

The account parameter is only available when the callback is being invoked for the first time (i.e., the user is being signed in). Subsequent invocations will only contain the token parameter.

NextAuth.js calculates it as Date.now() + refreshedTokens.expires_in * 1000, where expires_in is the number of seconds until expiration provided by the OAuth provider.

HKDF-SHA256 (HMAC-based Key Derivation Function with SHA-256). Keys are derived using HKDF-SHA256 to produce a 512-bit (64 byte) encryption key for A256CBC-HS512.

You can use 'openssl rand -base64 32' or visit https://generate-secret.vercel.app/32 to generate a random value.

next-auth.session-token (without the __Secure- prefix). The secure prefix is not used when NEXTAUTH_URL starts with http:// or is not set.

signIn (on successful sign in), signOut (on signout), createUser (user created), updateUser (user updated), linkAccount (account linked to a user), and session (session is active).

It will throw an error. NextAuth.js requires NEXTAUTH_SECRET in production to encrypt JWTs and hash email verification tokens.

Enables debug messages for authentication and database operations.

console (the built-in logger)

Error in handling the response from an OAuth provider.

In a folder outside /pages/api which is reserved for API code.

The email on the account is already linked, but not with this OAuth account.

All existing sessions are invalidated, logging out every user.

For increased security. NextAuth.js purposefully restricts the returned error codes.

false

Only credentials and email providers.

Could not create email provider user in the database.

Could not create OAuth provider user in the database.

pages.error (e.g., pages: { error: '/auth/error' })

The debug option is ignored when the logger option is set.

It causes a CallbackRouteError on your callback route.

Related to the Email provider - the token has expired or has already been used.

openssl rand -base64 32

Awaitable<string | boolean> - can return true, false, or a URL string

error, warn, and debug

OAuthSignin, OAuthCallback, OAuthCreateAccount, EmailCreateAccount, Callback, OAuthAccountNotLinked, EmailSignin, and CredentialsSignin.

Return null. Throwing an error inside authorize causes a CallbackRouteError.

As a query string parameter: ?error=

/api/auth/error

AccessDenied

Configuration (server configuration problem), AccessDenied (occurs when access is restricted through the signIn or redirect callback), Verification (related to Email provider - token expired or already used), and Default (catch-all error).

No, events are asynchronous functions that do not return a response. They are useful for audit logs/reporting or handling side-effects.

No. Redirects returned by the signIn callback cancel the authentication flow and should only redirect to error pages. Use the callbackUrl option or redirect callback for post-authentication redirects.

To hash JWT tokens, sign and encrypt session cookies, and generate public/private keys.

Currently only when the user verifies their email address.

error (string | undefined), status (number), ok (boolean - true if signin was successful), and url (string | null - null if there was an error).

It requires the URL to be an absolute URL at the same hostname, or a relative URL starting with a slash, otherwise it redirects to the homepage.

Sending the e-mail with the verification token failed.

A URL string (e.g., '/unauthorized')

The authorize callback returned null in the Credentials provider.

Error in constructing an authorization URL for the OAuth provider.

userId (not null, references users.id), type (not null), provider (not null), providerAccountId (not null), plus optional fields: refresh_token, access_token, expires_at, token_type, scope, id_token, session_state

pnpm add drizzle-orm @auth/drizzle-adapter

After the user successfully signs in by clicking the email link and the tokens match and haven't expired

@auth/drizzle-adapter

sessionToken (string), userId (string, references users.id), and expires (Date/timestamp)

The user's email address

Yes, MySQL varchar requires a length specification: varchar({ length: 255 })

id (primary key), name (nullable text), email (not null text), emailVerified (nullable timestamp), and image (nullable text)

drizzle-kit migrate or using the migrate() function programmatically

timestamp('emailVerified', { mode: 'date' })

npm install drizzle-orm @auth/drizzle-adapter

The compound primary key consists of userId and credentialID columns: primaryKey({ columns: [authenticator.userId, authenticator.credentialID] })

authenticatorsTable - used for WebAuthn/two-factor authentication

A hashed token using the AuthConfig.secret value

No, the length parameter is optional for PostgreSQL varchar according to PostgreSQL docs

The compound primary key consists of provider and providerAccountId columns: primaryKey({ columns: [account.provider, account.providerAccountId] })

The third parameter now requires an object with a columns array: primaryKey({ columns: [col1, col2] }) instead of primaryKey(col1, col2)

No, the sessionsTable is optional and only required if you're using the database session strategy.

credentialID (text, not null, unique), credentialPublicKey (text, not null), counter (integer, not null), userId (text, not null), providerAccountId (text, not null), credentialDeviceType (text, not null), credentialBackedUp (boolean, not null), and transports (text, optional)

A Drizzle database instance (db), which can be types like BaseSQLiteDatabase for SQLite or a database instance created with drizzle() for PostgreSQL/MySQL

cascade - references(() => users.id, { onDelete: 'cascade' })

The signature counter for WebAuthn authentication attempts to help prevent replay attacks

PostgreSQL and SQLite both use text() for string columns

PostgreSQL, MySQL, and SQLite

usersTable, accountsTable, sessionsTable, and verificationTokensTable

The compound primary key consists of identifier and token columns: primaryKey({ columns: [verificationToken.identifier, verificationToken.token] })

InstanceType

drizzle-kit must be installed as a dev dependency using: npm install drizzle-kit --save-dev or pnpm add drizzle-kit --save-dev

No, the verificationTokensTable is optional and only required if you're using a Magic Link provider.

Use .$defaultFn(() => crypto.randomUUID()) on the id field: id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID())

The first three tables use plural names (users, accounts, sessions) but verificationToken is singular

drizzle-kit push

identifier (text, not null), token (text, not null), and expires (timestamp, not null)

integer('expires_at')

import type { AdapterAccount } from '@auth/core/adapters' and use: type: text('type').$type<AdapterAccount['type']>().notNull()

Pass them as the second parameter: DrizzleAdapter(db, { usersTable: users, accountsTable: accounts, sessionsTable: sessions, verificationTokensTable: verificationTokens })

Auth.js v5 now builds on @auth/core with stricter OAuth/OIDC spec-compliance, which might break some existing OAuth providers that don't fully conform to the specifications.

Set trustHost: true (or AUTH_TRUST_HOST=true environment variable) in Docker environments or when running Auth.js behind a proxy. This allows Auth.js to trust the X-Forwarded-Host and X-Forwarded-Proto headers to auto-detect the host URL.

No, OAuth 1.0 support is deprecated in NextAuth v5.

Import the handlers from your auth.ts file and export GET and POST: import { handlers } from '@/auth'
export const { GET, POST } = handlers

Import from 'next-auth/react' (which is marked with 'use client') and wrap your component in SessionProvider: import { useSession, SessionProvider } from 'next-auth/react'. Client components using the hook must include the 'use client' directive.

export const { handlers, auth, signIn, signOut } = NextAuth({ providers: [...] })

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

In the config object, use: pages: { signIn: '/login' }. The key is the page type and the value is the path/route. You must ensure you actually have a page at the specified route.

The auth() function exported from your auth.ts config file replaces getServerSession. You import it with: import { auth } from '@/auth' and call it without passing authOptions: const session = await auth()

The authorize function now receives credentials through a destructured object: async authorize({ request }) instead of async authorize(credentials, req).

Both AUTH_URL and NEXTAUTH_URL are supported as aliases in v5 for backward compatibility. However, AUTH_URL is the recommended naming going forward and takes precedence if both are defined. AUTH_URL is mostly unnecessary in v5 as the host is inferred from request headers.

The oauth_token_secret and oauth_token fields can be removed from the account table if you are not using them.

signIn and signOut are exported from your centralized auth.ts config file: export const { auth, handlers, signIn, signOut } = NextAuth({ ... }). Import them with: import { signIn, signOut } from '@/auth' and use in server actions.

Import the auth function from your auth.ts config file and export it as middleware: import { auth } from '@/auth'
export const middleware = auth. The import next-auth/middleware from v4 is replaced.

The minimum required Next.js version is 14.0.

The default updateAge is 24 hours (86,400 seconds) when using database-persisted sessions. This setting is ignored when using JWT strategy.

For OAuth providers, follow this format: AUTH_{PROVIDER}_{ID|SECRET}. For example: AUTH_GITHUB_ID and AUTH_GITHUB_SECRET will be automatically detected and used without explicit configuration.

AUTH_SECRET is the only environment variable that is really necessary. You do not need to additionally pass this value into your config as the secret configuration option if you've set the environment variable.

declare module '@auth/core' instead of 'next-auth' (from v4). For JWT types, use: declare module '@auth/core/jwt'.

When using the auth() function in v5, the session() callback is ignored. The auth() function will expose anything returned from the jwt() callback (or from the User if using a 'database' strategy) because auth() is always on the server.

No, installing @auth/core is not necessary. NextAuth v5 builds on @auth/core internally, and as a user you should never have to interact with @auth/core directly.

The default maxAge is 30 days (30 * 24 * 60 * 60 = 2,592,000 seconds).

pnpm: 'pnpm add next-auth@beta', yarn: 'yarn add next-auth@beta', bun: 'bun add next-auth@beta'

The configuration is now in a file named auth.ts in the root of your repository (or in the src folder if you have one), instead of in the API route pages/api/auth/[...nextauth].ts.

Adapter packages are renamed from @next-auth/-adapter to @auth/-adapter. For example: @next-auth/prisma-adapter becomes @auth/prisma-adapter.

NextAuth.js v5 can automatically infer environment variables that are prefixed with AUTH_ instead of NEXTAUTH_. For example: AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, AUTH_URL, AUTH_SECRET.

No, NextAuth.js v5 does not introduce any breaking changes to the database schema.

The session cookie name changed from next-auth.session-token (v4) to authjs.session-token (v5).

Import CredentialsSignin and create a custom error class: import { CredentialsSignin } from 'next-auth'
class InvalidLoginError extends CredentialsSignin { code = 'Invalid identifier or password' }
Then throw new InvalidLoginError() in the authorize function.

npm install next-auth@beta

Create a separate auth.config.ts file that exports a configuration object without database adapters or edge-incompatible code. Import this config in your middleware and use it to initialize Auth.js there, avoiding database adapter imports.

Only the 'jwt' session strategy is supported in Edge runtime. The database session strategy is not compatible with Edge runtime depending on the database driver package.

Run 'npx auth secret' in your project's root directory and it will autogenerate a random value and put it in your .env.local file. Alternatively, use 'openssl rand -base64 32' or https://generate-secret.vercel.app/32.

The default session strategy is 'jwt' (an encrypted JWT stored in the session cookie) when no adapter is configured.

When you use an adapter, it defaults to the 'database' session strategy instead of 'jwt'.