Skip to main content

types

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

Installation​

npm install @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​

Type Aliases​

ErrorPageParam​

"Configuration" | "AccessDenied" | "Verification"

TODO: Check if all these are used/correct

SignInPageErrorParam​

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

TODO: Check if all these are used/correct

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​

string

Provider's id for this account. Eg.: "google"

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
type​

ProviderType

Provider's type for this account

userId?​

string

id of the user this account belongs to

CallbacksOptions​

Documentation

Type parameters​

Properties​

jwt​

Function

Type declaration​

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

####### Signature

(params: object): Awaitable<null | JWT>;

####### Parameters

NameType
paramsobject
params.tokenJWT
params.account?null | A
params.isNewUser?boolean
params.profile?P
params.user?User | AdapterUser

####### Returns

Awaitable<null | JWT>

redirect​

Function

Type declaration​

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

####### Signature

(params: object): Awaitable<string>;

####### Parameters

NameTypeDescription
paramsobject-
params.baseUrlstringDefault base URL of site (can be used as fallback)
params.urlstringURL provided as callback URL by the client

####### Returns

Awaitable<string>

session​

Function

Type declaration​

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 |

####### Signature

(params: object): Awaitable<Session>;

####### Parameters

NameType
paramsobject
params.sessionSession
params.tokenJWT
params.userUser | AdapterUser

####### Returns

Awaitable<Session>

signIn​

Function

Type declaration​

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

####### Signature

(params: object): Awaitable<boolean>;

####### Parameters

NameTypeDescription
paramsobject-
params.accountnull | A-
params.userUser | AdapterUser-
params.credentials?Record<string, CredentialInput>If Credentials provider is used, it contains the user credentials
params.email?objectIf 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?PIf 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​

Function

Type declaration​

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.

####### Signature

(message: object): Awaitable<void>;

####### Parameters

NameType
messageobject
message.sessionSession
message.tokenJWT

####### Returns

Awaitable<void>

signIn​

Function

Type declaration​

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.

####### Signature

(message: object): Awaitable<void>;

####### Parameters

NameType
messageobject
message.accountnull | Account
message.userUser
message.isNewUser?boolean
message.profile?Profile

####### Returns

Awaitable<void>

signOut​

Function

Type declaration​

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.

####### Signature

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

####### Parameters

NameType
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

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