types

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

Installation

npm install @auth/core

pnpm add @auth/core

yarn add @auth/core

bun add @auth/core

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

Usage

Even if you don’t use TypeScript, IDEs like VS Code 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.

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
    },
  }
})

Resources

• TypeScript - The Basics
• Extending built-in types

AuthConfig

Re-exports AuthConfig

Account

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

Extends

• Partial<TokenEndpointResponse>

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 TokenEndpointResponse.expires_in.

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

This value can be used for implementing token rotation together with TokenEndpointResponse.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. E.g. “google”. See the full list at https://authjs.dev/reference/core/providers

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

Authenticator

A webauthn authenticator. Represents an entity capable of authenticating the account it references, and contains the auhtenticator’s credentials and related information.

See

https://www.w3.org/TR/webauthn/#authenticator

Extended by

• AdapterAuthenticator

Properties

counter

counter: number;

Number of times the authenticator has been used.

credentialBackedUp

credentialBackedUp: boolean;

Whether the client authenticator backed up the credential.

credentialDeviceType

credentialDeviceType: string;

Device type of the authenticator.

credentialID

credentialID: string;

Base64 encoded credential ID.

credentialPublicKey

credentialPublicKey: string;

Base64 encoded credential public key.

providerAccountId

providerAccountId: string;

The provider account ID connected to the authenticator.

transports?

optional transports: null | string;

Concatenated transport flags.

userId?

optional userId: string;

ID of the user this authenticator belongs to.

CookieOption

Documentation

Properties

name

name: string;

options

options: CookieSerializeOptions;

CookiesOptions

Documentation

Properties

callbackUrl

callbackUrl: Partial<CookieOption>;

csrfToken

csrfToken: Partial<CookieOption>;

nonce

nonce: Partial<CookieOption>;

pkceCodeVerifier

pkceCodeVerifier: Partial<CookieOption>;

sessionToken

sessionToken: Partial<CookieOption>;

state

state: Partial<CookieOption>;

webauthnChallenge

webauthnChallenge: Partial<CookieOption>;

DefaultSession

Extended by

• Session

Properties

expires

expires: string;

user?

optional user: User;

LoggerInstance

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

Documentation

Extends

• Record<string, Function>

Properties

debug()

debug: (message, metadata?) => void;

Parameters

Returns

void

error()

error: (error) => void;

Parameters

Returns

void

warn()

warn: (code) => void;

Parameters

Returns

void

PagesOptions

Properties

error

error: string;

The path to the error page.

The optional “error” query parameter is set to one of the available values.

Default

"/error"

newUser

newUser: string;

If set, new users will be directed here on first sign in

signIn

signIn: string;

The path to the sign in page.

The optional “error” query parameter is set to one of the available values.

Default

"/signin"

signOut

signOut: string;

verifyRequest

verifyRequest: string;

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;

PublicProvider

Properties

callbackUrl

callbackUrl: string;

id

id: string;

name

name: string;

signinUrl

signinUrl: string;

type

type: string;

ResponseInternal<Body>

Type parameters

Properties

body?

optional body: Body;

cookies?

optional cookies: Cookie[];

headers?

optional headers: HeadersInit;

redirect?

optional redirect: string;

status?

optional status: number;

Session

The active session of the logged in user.

Extends

• DefaultSession

Properties

expires

expires: string;

Inherited from

DefaultSession.expires

user?

optional user: User;

Inherited from

DefaultSession.user

Theme

Change the theme of the built-in pages.

Documentation | Pages

Properties

brandColor?

optional brandColor: string;

buttonText?

optional buttonText: string;

colorScheme?

optional colorScheme: "auto" | "dark" | "light";

logo?

optional logo: string;

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

• AdapterUser

Properties

email?

optional email: null | string;

id?

optional id: string;

image?

optional image: null | string;

name?

optional name: null | string;

AuthAction

type AuthAction: 
  | "callback"
  | "csrf"
  | "error"
  | "providers"
  | "session"
  | "signin"
  | "signout"
  | "verify-request"
  | "webauthn-options";

Supported actions by Auth.js. Each action map to a REST API endpoint. Some actions have a GET and POST variant, depending on if the action changes the state of the server.

• "callback":
  • GET: Handles the callback from an OAuth provider.
  • POST: Handles the callback from a Credentials provider.
• "csrf": Returns the raw CSRF token, which is saved in a cookie (encrypted). It is used for CSRF protection, implementing the double submit cookie technique.

• "error": Renders the built-in error page.
• "providers": Returns a client-safe list of all configured providers.
• "session":
  • GET: Returns the user’s session if it exists, otherwise null.
  • POST: Updates the user’s session and returns the updated session.
• "signin":
  • GET: Renders the built-in sign-in page.
  • POST: Initiates the sign-in flow.
• "signout":
  • GET: Renders the built-in sign-out page.
  • POST: Initiates the sign-out flow. This will invalidate the user’s session (deleting the cookie, and if there is a session in the database, it will be deleted as well).
• "verify-request": Renders the built-in verification request page.
• "webauthn-options":
  • GET: Returns the options for the WebAuthn authentication and registration flows.

Awaitable<T>

type Awaitable<T>: T | PromiseLike<T>;

Type parameters

Awaited<T>

type Awaited<T>: T extends Promise<infer U> ? U : T;

Type parameters

ErrorPageParam

type ErrorPageParam: "Configuration" | "AccessDenied" | "Verification";

TODO: Check if all these are used/correct

SemverString

type SemverString: v${number} | v${number}.${number} | v${number}.${number}.${number};

SignInPageErrorParam

type SignInPageErrorParam: 
  | "Signin"
  | "OAuthSignin"
  | "OAuthCallbackError"
  | "OAuthCreateAccount"
  | "EmailCreateAccount"
  | "Callback"
  | "OAuthAccountNotLinked"
  | "EmailSignin"
  | "CredentialsSignin"
  | "SessionRequired";

TODO: Check if all these are used/correct

TokenSet

type TokenSet: Partial<TokenEndpointResponse> & {
  expires_at: number;
};

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

Type declaration

expires_at?

optional expires_at: number;

Date of when the access_token expires in seconds. This value is calculated from the expires_in value.

See

https://www.ietf.org/rfc/rfc6749.html#section-4.2.2

WebAuthnOptionsResponseBody

type WebAuthnOptionsResponseBody: {
  action: WebAuthnAuthenticate;
  options: PublicKeyCredentialRequestOptionsJSON;
  } | {
  action: WebAuthnRegister;
  options: PublicKeyCredentialCreationOptionsJSON;
};