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:
import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"
export const { handlers, auth } = NextAuth({ providers: [ GitHub ] })
And the .env.local
file:
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:
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
Parameter | Type |
---|---|
message ? | string | ErrorOptions |
errorOptions ? | ErrorOptions |
Returns
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
Parameter | Type |
---|---|
err | Error |
stackTraces | CallSite [] |
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
Parameter | Type |
---|---|
targetObject | object |
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:
- The user is redirected to the signin page, with
error=CredentialsSignin&code=credentials
in the URL.code
is configurable. - 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
Error
Constructors
new CredentialsSignin(message)
new CredentialsSignin(message?): CredentialsSignin
Parameters
Parameter | Type |
---|---|
message ? | string |
Returns
Inherited from
Error.constructor
new CredentialsSignin(message, options)
new CredentialsSignin(message?, options?): CredentialsSignin
Parameters
Parameter | Type |
---|---|
message ? | string |
options ? | ErrorOptions |
Returns
Inherited from
Error.constructor
Properties
cause?
optional cause: unknown;
Inherited from
Error.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
Error.message
name
name: string;
Inherited from
Error.name
stack?
optional stack: string;
Inherited from
Error.stack
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
Parameter | Type |
---|---|
err | Error |
stackTraces | CallSite [] |
Returns
any
Inherited from
Error.prepareStackTrace
stackTraceLimit
static stackTraceLimit: number;
Inherited from
Error.stackTraceLimit
type
static type: string;
Methods
captureStackTrace()
static captureStackTrace(targetObject, constructorOpt?): void
Create .stack property on a target object
Parameters
Parameter | Type |
---|---|
targetObject | object |
constructorOpt ? | Function |
Returns
void
Inherited from
Error.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
authorization_details?
optional readonly authorization_details: AuthorizationDetails[];
Inherited from
Partial.authorization_details
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
- https://authjs.dev/guides/refresh-token-rotation#database-strategy
- https://www.rfc-editor.org/rfc/rfc6749#section-5.1
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 theauthorize()
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: 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
Omit
<AuthConfig
,"raw"
>
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: {
jwt: (params) => Awaitable<null | JWT>;
redirect: (params) => Awaitable<string>;
session: (params) => Awaitable<Session | DefaultSession>;
signIn: (params) => Awaitable<string | boolean>;
} & {
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
jwt()?
optional jwt: (params) => Awaitable<null | JWT>;
This callback is called whenever a JSON Web Token is created (i.e. at sign in) or updated (i.e whenever a session is accessed in the client). Anything you return here will be saved in the JWT and forwarded to the session callback. There you can control what should be returned to the client. Anything else will be kept from your frontend. The JWT is encrypted by default via your AUTH_SECRET environment variable.
Parameters
Parameter | Type | Description |
---|---|---|
params | Object | - |
params.account | null | Account | Contains information about the provider that was used to sign in. Also includes TokenSet Note available when trigger is "signIn" or "signUp" |
params.isNewUser ? | boolean | Deprecated use trigger === "signUp" instead |
params.profile ? | Profile | The OAuth profile returned from your provider. (In case of OIDC it will be the decoded ID Token or /userinfo response) Note available when trigger is "signIn" . |
params.session ? | any | When using AuthConfig.session strategy: "jwt" , this is the datasent from the client via the useSession().update method.⚠ Note, you should validate this data before using it. |
params.token | JWT | When trigger is "signIn" or "signUp" , it will be a subset of JWT,name , email and image will be included.Otherwise, it will be the full JWT for subsequent calls. |
params.trigger ? | "signIn" | "update" | "signUp" | Check why was the jwt callback invoked. Possible reasons are: - user sign-in: First time the callback is invoked, user , profile and account will be present.- user sign-up: a user is created for the first time in the database (when AuthConfig.session.strategy is set to "database" )- update event: Triggered by the useSession().update method.In case of the latter, trigger will be undefined . |
params.user | AdapterUser | User | Either the result of the OAuthConfig.profile or the CredentialsConfig.authorize callback. Note available when trigger is "signIn" or "signUp" .Resources: - Credentials Provider - User database model |
Returns
redirect()?
optional redirect: (params) => Awaitable<string>;
This callback is called anytime the user is redirected to a callback URL (i.e. on signin or signout). By default only URLs on the same host as the origin are allowed. You can use this callback to customise that behaviour.
Example
callbacks: {
async redirect({ url, baseUrl }) {
// Allows relative callback URLs
if (url.startsWith("/")) return `${baseUrl}${url}`
// Allows callback URLs on the same origin
if (new URL(url).origin === baseUrl) return url
return baseUrl
}
}
Parameters
Parameter | Type | Description |
---|---|---|
params | Object | - |
params.baseUrl | string | Default base URL of site (can be used as fallback) |
params.url | string | URL provided as callback URL by the client |
Returns
Awaitable
<string
>
session()?
optional session: (params) => Awaitable<Session | DefaultSession>;
This callback is called whenever a session is checked.
(i.e. when invoking the /api/session
endpoint, using useSession
or getSession
).
The return value will be exposed to the client, so be careful what you return here!
If you want to make anything available to the client which you’ve added to the token
through the JWT callback, you have to explicitly return it here as well.
⚠ By default, only a subset (email, name, image) of the token is returned for increased security.
The token argument is only available when using the jwt session strategy, and the user argument is only available when using the database session strategy.
Example
callbacks: {
async session({ session, token, user }) {
// Send properties to the client, like an access_token from a provider.
session.accessToken = token.accessToken
return session
}
}
Parameters
Parameter | Type |
---|---|
params | { session : { user : AdapterUser ; } & AdapterSession ; user : AdapterUser ; } & { session : Session ; token : JWT ; } & { newSession : any ; trigger : "update" ; } |
Returns
Awaitable
<Session
| DefaultSession
>
signIn()?
optional signIn: (params) => Awaitable<string | boolean>;
Controls whether a user is allowed to sign in or not.
Returning true
continues the sign-in flow.
Returning false
or throwing an error will stop the sign-in flow and redirect the user to the error page.
Returning a string will redirect the user to the specified URL.
Unhandled errors will throw an AccessDenied
with the message set to the original error.
Example
callbacks: {
async signIn({ profile }) {
// Only allow sign in for users with email addresses ending with "yourdomain.com"
return profile?.email?.endsWith("@yourdomain.com")
}
Parameters
Parameter | Type | Description |
---|---|---|
params | Object | - |
params.account | null | Account | - |
params.credentials ? | Record <string , CredentialInput > | If Credentials provider is used, it contains the user credentials |
params.email ? | Object | If Email provider is used, on the first call, it contains averificationRequest: true property to indicate it is being triggered in the verification request flow.When the callback is invoked after a user has clicked on a sign in link, this property will not be present. You can check for the verificationRequest propertyto avoid sending emails to addresses or domains on a blocklist or to only explicitly generate them for email address in an allow list. |
params.email.verificationRequest ? | boolean | - |
params.profile ? | Profile | If OAuth provider is used, it contains the full OAuth profile returned by your provider. |
params.user | AdapterUser | User | - |
Returns
Awaitable
<string
| boolean
>
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
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
Parameter | Type | Description |
---|---|---|
params | Object | - |
params.auth | null | Session | The authenticated user or token, if any. |
params.request | NextRequest | The 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.
- ⚠ If you added a custom AuthConfig.logger, this setting is ignored.
Default
false
Inherited from
Omit.debug
events?
optional events: {
createUser: (message) => Awaitable<void>;
linkAccount: (message) => Awaitable<void>;
session: (message) => Awaitable<void>;
signIn: (message) => Awaitable<void>;
signOut: (message) => Awaitable<void>;
updateUser: (message) => Awaitable<void>;
};
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
{}
createUser()?
optional createUser: (message) => Awaitable<void>;
Parameters
Parameter | Type |
---|---|
message | Object |
message.user | User |
Returns
Awaitable
<void
>
linkAccount()?
optional linkAccount: (message) => Awaitable<void>;
Parameters
Parameter | Type |
---|---|
message | Object |
message.account | Account |
message.profile | AdapterUser | User |
message.user | AdapterUser | User |
Returns
Awaitable
<void
>
session()?
optional session: (message) => Awaitable<void>;
The message object will contain one of these depending on if you use JWT or database persisted sessions:
token
: The JWT for this session.session
: The session object from your adapter.
Parameters
Parameter | Type |
---|---|
message | Object |
message.session | Session |
message.token | JWT |
Returns
Awaitable
<void
>
signIn()?
optional signIn: (message) => Awaitable<void>;
If using a credentials
type auth, the user is the raw response from your
credential provider.
For other providers, you’ll get the User object from your adapter, the account,
and an indicator if the user was new to your Adapter.
Parameters
Parameter | Type |
---|---|
message | Object |
message.account | null | Account |
message.isNewUser ? | boolean |
message.profile ? | Profile |
message.user | User |
Returns
Awaitable
<void
>
signOut()?
optional signOut: (message) => Awaitable<void>;
The message object will contain one of these depending on if you use JWT or database persisted sessions:
token
: The JWT for this session.session
: The session object from your adapter that is being ended.
Parameters
Parameter | Type |
---|---|
message | { session : undefined | null | void | AdapterSession ; } | { token : null | JWT ; } |
Returns
Awaitable
<void
>
updateUser()?
optional updateUser: (message) => Awaitable<void>;
Parameters
Parameter | Type |
---|---|
message | Object |
message.user | User |
Returns
Awaitable
<void
>
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)
}
}
})
- ⚠ When set, the AuthConfig.debug option is ignored
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
export { auth as middleware } from "./auth"
Alternatively you can wrap your own middleware with auth
, where req
is extended with auth
:
Example
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
import { auth } from "../auth"
export default async function Page() {
const { user } = await auth()
return <p>Hello {user?.name}</p>
}
In Route Handlers
Example
import { auth } from "../../auth"
export const POST = auth((req) => {
// req.auth
})
In Edge API Routes
Example
import { auth } from "../../auth"
export default auth((req) => {
// req.auth
})
export const config = { runtime: "edge" }
In API Routes
Example
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
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
:
export { GET, POST } from "../../../../auth"
export const runtime = "edge" // optional
Then 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 with a relative path.
Example
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:
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 parameter | Value |
---|---|
P extends BuiltInProviderType | string & {} | - |
R extends boolean | true |
Parameters
Parameter | Type | Description |
---|---|---|
provider ? | P | Provider 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 with a relative path.
Example
import { signOut } from "../auth"
export default function Layout() {
return (
<form action={async () => {
"use server"
await signOut()
}}>
<button>Sign out</button>
</form>
)
Type parameters
Type parameter | Value |
---|---|
R extends boolean | true |
Parameters
Parameter | Type | Description |
---|---|---|
options ? | Object | - |
options.redirect ? | R | If set to false , the signOut method will return the URL to redirect to instead of redirecting automatically. |
options.redirectTo ? | string | The relative path 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
Parameter | Type |
---|---|
data | Partial <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
user?
optional user: User;
Inherited from
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
Parameter | Type |
---|---|
config | NextAuthConfig | (request ) => Awaitable <NextAuthConfig > |
Returns
Example
import NextAuth from "next-auth"
import GitHub from "@auth/core/providers/github"
export const { handlers, auth } = NextAuth({ providers: [GitHub] })
Lazy initialization:
Example
import NextAuth from "next-auth"
import GitHub from "@auth/core/providers/github"
export const { handlers, auth } = NextAuth(async (req) => {
console.log(req) // do something with the request
return {
providers: [GitHub],
},
})