types

This module contains public types and interfaces of the core package.

Installation

npm

npm install @auth/core

yarn

yarn add @auth/core

pnpm

pnpm add @auth/core

You can then import this submodule from @auth/core/type.

Usage

Even if you don't use TypeScript, IDEs like VSCode will pick up types to provide you with a better developer experience. While you are typing, you will get suggestions about what certain objects/functions look like, and sometimes links to documentation, examples, and other valuable resources.

Generally, you will not need to import types from this module. Mostly when using the Auth function and optionally the AuthConfig interface, everything inside there will already be typed.

tip

Inside the Auth function, you won't need to use a single type from this module.

Example

index.ts

import { Auth } from "@auth/core"

const request = new Request("https://example.com")
const response = await Auth(request, {
  callbacks: {
    jwt(): JWT { // <-- This is unnecessary!
      return { foo: "bar" }
    },
    session(
       { session, token }: { session: Session; token: JWT } // <-- This is unnecessary!
    ) {
      return session
    },
  }
})

info

We are advocates of TypeScript, as it will help you catch errors at build-time, before your users do. 😉

Resources

• TypeScript - The Basics
• Extending built-in types

Type Aliases

ErrorPageParam

ErrorPageParam: "Configuration" | "AccessDenied" | "Verification"

TODO: Check if all these are used/correct

---

SignInPageErrorParam

SignInPageErrorParam: "Signin" | "OAuthSignin" | "OAuthCallback" | "OAuthCreateAccount" | "EmailCreateAccount" | "Callback" | "OAuthAccountNotLinked" | "EmailSignin" | "CredentialsSignin" | "SessionRequired"

TODO: Check if all these are used/correct

---

TokenSet

TokenSet: Partial<OAuth2TokenEndpointResponse | OpenIDTokenEndpointResponse>

Different tokens returned by OAuth Providers. Some of them are available with different casing, but they refer to the same value.

Interfaces

Account

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

Properties

provider

provider: string

id of the provider used for this account

providerAccountId

providerAccountId: string

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

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

type

type: ProviderType

Provider's type for this account

userId

userId?: string

id of the user this account belongs to.

---

CallbacksOptions<P, A>

Documentation

Type parameters

• P = Profile
• A = Account

Properties

jwt

jwt: Function

Type declaration

####### Signature

(params: Object): 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). Its content is forwarded to the session callback, where you can control what should be returned to the client. Anything else will be kept inaccessible from the client.

Returning null will invalidate the JWT session by clearing the user's cookies. You'll still have to monitor and invalidate unexpired tokens from future requests yourself to prevent unauthorized access.

By default the JWT is encrypted.

Documentation | session callback

####### Parameters

Name	Type
params	Object
params.token	JWT
params.account?	null | A
params.isNewUser?	boolean
params.profile?	P
params.user?	User | AdapterUser

####### Returns

Awaitable<null | JWT>

redirect

redirect: Function

Type declaration

####### Signature

(params: Object): Awaitable<string>

This callback is called anytime the user is redirected to a callback URL (e.g. on signin or signout). By default only URLs on the same URL as the site are allowed, you can use this callback to customise that behaviour.

Documentation

####### Parameters

Name	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

session: Function

Type declaration

####### Signature

(params: Object): Awaitable<Session>

This callback is called whenever a session is checked. (Eg.: invoking the /api/session endpoint, using useSession or getSession)

⚠ By default, only a subset (email, name, image) of the token is returned for increased security.

If you want to make something available you added to the token through the jwt callback, you have to explicitly forward it here to make it available to the client.

Documentation | jwt callback | useSession | getSession |

####### Parameters

Name	Type
params	Object
params.session	Session
params.token	JWT
params.user	User | AdapterUser

####### Returns

Awaitable<Session>

signIn

signIn: Function

Type declaration

####### Signature

(params: Object): Awaitable<boolean>

Control whether a user is allowed to sign in or not. Returning true continues the sign-in flow, while returning false redirects to the PagesOptions.error error page. The error parameter is set to AccessDenied.

Unhandled errors are redirected to the error page The error parameter is set to Configuration. an AuthorizedCallbackError is logged on the server.

####### See

https://authjs.dev/reference/errors#authorizedcallbackerror

####### Todo

rename to authorized

####### Parameters

Name	Type	Description
params	Object	-
params.account	null | A	-
params.user	User | AdapterUser	-
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 a verificationRequest: 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 property to 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?	P	If OAuth provider is used, it contains the full OAuth profile returned by your provider.

####### Returns

Awaitable<boolean>

---

CookieOption

Documentation

---

CookiesOptions

Documentation

---

EventCallbacks

The various event callbacks you can register for from next-auth

Documentation

Properties

session

session: Function

Type declaration

####### Signature

(message: Object): Awaitable<void>

The message object will contain one of these depending on if you use JWT or database persisted sessions:

• token: The JWT token for this session.
• session: The session object from your adapter.

####### Parameters

Name	Type
message	Object
message.session	Session
message.token	JWT

####### Returns

Awaitable<void>

signIn

signIn: Function

Type declaration

####### Signature

(message: Object): 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

Name	Type
message	Object
message.account	null | Account
message.user	User
message.isNewUser?	boolean
message.profile?	Profile

####### Returns

Awaitable<void>

signOut

signOut: Function

Type declaration

####### Signature

(message: { session: undefined | null | void | AdapterSession  } | { token: null | JWT  }): Awaitable<void>

The message object will contain one of these depending on if you use JWT or database persisted sessions:

• token: The JWT token for this session.
• session: The session object from your adapter that is being ended.

####### Parameters

Name	Type
message	{ session: undefined | null | void | AdapterSession } | { token: null | JWT }

####### Returns

Awaitable<void>

---

LoggerInstance

Override any of the methods, and the rest will use the default logger.

Documentation

---

Profile

The OAuth profile returned from your provider

---

Session

Returned by useSession, getSession, returned by the session callback and also the shape received as a prop on the SessionProvider React Context

useSession | getSession | SessionProvider | session callback

---

SessionOptions

Documentation

Properties

generateSessionToken

generateSessionToken: Function

Type declaration

####### Signature

(): 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

maxAge: number

Relative time from now in seconds when to expire the session

Default

2592000 // 30 days

strategy

strategy: SessionStrategy

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

updateAge: number

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

Default

86400 // 1 day

---

Theme

Change the theme of the built-in pages.

Documentation | Pages

---

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.

signIn callback | session callback | jwt callback | profile OAuth provider callback