Skip to content
Migrating from NextAuth.js v4? Read our migration guide.
API reference
@auth/core
providers

providers

CredentialInput

Re-exports CredentialInput

CredentialsConfig

Re-exports CredentialsConfig

CredentialsProviderType

Re-exports CredentialsProviderType

EmailConfig

Re-exports EmailConfig

EmailProviderType

Re-exports EmailProviderType

EmailUserConfig

Re-exports EmailUserConfig

AppProvider

Shared across all ProviderType

Extends

Properties

callbackUrl

callbackUrl: string;

id

id: string;

Uniquely identifies the provider in AuthConfig.providers It’s also part of the URL

Inherited from

CommonProviderOptions.id

name

name: string;

The provider name used on the default sign-in page’s sign-in button. For example if it’s “Google”, the corresponding button will say: “Sign in with Google”

Inherited from

CommonProviderOptions.name

signinUrl

signinUrl: string;

type

type: ProviderType;

See ProviderType

Inherited from

CommonProviderOptions.type

CommonProviderOptions

Shared across all ProviderType

Extended by

Properties

id

id: string;

Uniquely identifies the provider in AuthConfig.providers It’s also part of the URL

name

name: string;

The provider name used on the default sign-in page’s sign-in button. For example if it’s “Google”, the corresponding button will say: “Sign in with Google”

type

type: ProviderType;

See ProviderType

OAuth2Config<Profile>

TODO: Document

Extends

Type parameters

Type parameter
Profile

Properties

account?

optional account: AccountCallback;

Receives the full TokenSet returned by the OAuth provider, and returns a subset. It is used to create the account associated with a user in the database.

You need to adjust your database’s Account model to match the returned properties. Check out the documentation of your database adapter for more information.

Defaults to: access_token, id_token, refresh_token, expires_at, scope, token_type, session_state

Example
import GitHub from "@auth/core/providers/github"
// ...
GitHub({
  account(account) {
    // https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens#refreshing-a-user-access-token-with-a-refresh-token
    const refresh_token_expires_at =
      Math.floor(Date.now() / 1000) + Number(account.refresh_token_expires_in)
    return {
      access_token: account.access_token,
      expires_at: account.expires_at,
      refresh_token: account.refresh_token,
      refresh_token_expires_at
    }
  }
})
See

allowDangerousEmailAccountLinking?

optional allowDangerousEmailAccountLinking: boolean;

Normally, when you sign in with an OAuth provider and another account with the same email address already exists, the accounts are not linked automatically.

Automatic account linking on sign in is not secure between arbitrary providers and is disabled by default. Learn more in our Security FAQ.

However, it may be desirable to allow automatic account linking if you trust that the provider involved has securely verified the email address associated with the account. Set allowDangerousEmailAccountLinking: true to enable automatic account linking.

authorization?

optional authorization: string | AuthorizationEndpointHandler;

The login process will be initiated by sending the user to this URL.

Authorization endpoint

checks?

optional checks: ("none" | "state" | "pkce")[];

The CSRF protection performed on the callback endpoint.

Default
["pkce"]
Note

When redirectProxyUrl or AuthConfig.redirectProxyUrl is set, "state" will be added to checks automatically.

RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE) | RFC 6749 - The OAuth 2.0 Authorization Framework | OpenID Connect Core 1.0 |

client?

optional client: Partial<Client>;

Pass overrides to the underlying OAuth library. See oauth4webapi client for details.

clientId?

optional clientId: string;

clientSecret?

optional clientSecret: string;

id

id: string;

Identifies the provider when you want to sign in to a specific provider.

Example
signIn('github') // "github" is the provider ID
Overrides

CommonProviderOptions.id

issuer?

optional issuer: string;
Overrides

PartialIssuer.issuer

jwks_endpoint

jwks_endpoint: any;
Inherited from

PartialIssuer.jwks_endpoint

name

name: string;

The name of the provider. shown on the default sign in page.

Overrides

CommonProviderOptions.name

profile?

optional profile: ProfileCallback<Profile>;

Receives the full Profile returned by the OAuth provider, and returns a subset. It is used to create the user in the database.

Defaults to: id, email, name, image

See

Database Adapter: User model

redirectProxyUrl?

optional redirectProxyUrl: string;

style?

optional style: OAuthProviderButtonStyles;

token?

optional token: string | TokenEndpointHandler;

type

type: "oauth";

See ProviderType

Overrides

CommonProviderOptions.type

userinfo?

optional userinfo: string | UserinfoEndpointHandler;

wellKnown?

optional wellKnown: string;

OpenID Connect (OIDC) compliant providers can configure this instead of authorize/token/userinfo options without further configuration needed in most cases. You can still use the authorize/token/userinfo options for advanced control.

Authorization Server Metadata

OAuthProviderButtonStyles

Properties

bg?

optional bg: string;
Deprecated

Please use ‘brandColor’ instead

brandColor?

optional brandColor: string;

logo?

optional logo: string;

text?

optional text: string;
Deprecated

OIDCConfig<Profile>

Extension of the OAuth2Config.

See

https://openid.net/specs/openid-connect-core-1_0.html

Extends

Type parameters

Type parameter
Profile

Properties

account?

optional account: AccountCallback;

Receives the full TokenSet returned by the OAuth provider, and returns a subset. It is used to create the account associated with a user in the database.

You need to adjust your database’s Account model to match the returned properties. Check out the documentation of your database adapter for more information.

Defaults to: access_token, id_token, refresh_token, expires_at, scope, token_type, session_state

Example
import GitHub from "@auth/core/providers/github"
// ...
GitHub({
  account(account) {
    // https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens#refreshing-a-user-access-token-with-a-refresh-token
    const refresh_token_expires_at =
      Math.floor(Date.now() / 1000) + Number(account.refresh_token_expires_in)
    return {
      access_token: account.access_token,
      expires_at: account.expires_at,
      refresh_token: account.refresh_token,
      refresh_token_expires_at
    }
  }
})
See
Inherited from

Omit.account

allowDangerousEmailAccountLinking?

optional allowDangerousEmailAccountLinking: boolean;

Normally, when you sign in with an OAuth provider and another account with the same email address already exists, the accounts are not linked automatically.

Automatic account linking on sign in is not secure between arbitrary providers and is disabled by default. Learn more in our Security FAQ.

However, it may be desirable to allow automatic account linking if you trust that the provider involved has securely verified the email address associated with the account. Set allowDangerousEmailAccountLinking: true to enable automatic account linking.

Inherited from

Omit.allowDangerousEmailAccountLinking

authorization?

optional authorization: string | AuthorizationEndpointHandler;

The login process will be initiated by sending the user to this URL.

Authorization endpoint

Inherited from

Omit.authorization

checks?

optional checks: ("none" | "state" | "nonce" | "pkce")[];

client?

optional client: Partial<Client>;

Pass overrides to the underlying OAuth library. See oauth4webapi client for details.

Inherited from

Omit.client

clientId?

optional clientId: string;
Inherited from

Omit.clientId

clientSecret?

optional clientSecret: string;
Inherited from

Omit.clientSecret

id

id: string;

Identifies the provider when you want to sign in to a specific provider.

Example
signIn('github') // "github" is the provider ID
Inherited from

Omit.id

idToken?

optional idToken: boolean;

If set to false, the userinfo_endpoint will be fetched for the user data.

Note

An id_token is still required to be returned during the authorization flow.

issuer?

optional issuer: string;
Inherited from

Omit.issuer

jwks_endpoint

jwks_endpoint: any;
Inherited from

Omit.jwks_endpoint

name

name: string;

The name of the provider. shown on the default sign in page.

Inherited from

Omit.name

profile?

optional profile: ProfileCallback<Profile>;

Receives the full Profile returned by the OAuth provider, and returns a subset. It is used to create the user in the database.

Defaults to: id, email, name, image

See

Database Adapter: User model

Inherited from

Omit.profile

redirectProxyUrl?

optional redirectProxyUrl: string;
Inherited from

Omit.redirectProxyUrl

style?

optional style: OAuthProviderButtonStyles;
Inherited from

Omit.style

token?

optional token: string | TokenEndpointHandler;
Inherited from

Omit.token

type

type: "oidc";

userinfo?

optional userinfo: string | UserinfoEndpointHandler;
Inherited from

Omit.userinfo

wellKnown?

optional wellKnown: string;

OpenID Connect (OIDC) compliant providers can configure this instead of authorize/token/userinfo options without further configuration needed in most cases. You can still use the authorize/token/userinfo options for advanced control.

Authorization Server Metadata

Inherited from

Omit.wellKnown

AccountCallback()

type AccountCallback: (tokens) => TokenSet | undefined | void;

Parameters

ParameterType
tokensTokenSet

Returns

TokenSet | undefined | void

AppProviders

type AppProviders: (Provider | ReturnType<BuiltInProviders[keyof BuiltInProviders]>)[];

AuthorizationEndpointHandler

type AuthorizationEndpointHandler: EndpointHandler<AuthorizationParameters>;

BuiltInProviderType

type BuiltInProviderType: RedirectableProviderType | OAuthProviderType | WebAuthnProviderType;

BuiltInProviders

type BuiltInProviders: Record<OAuthProviderType, (config) => OAuthConfig<any>> & Record<CredentialsProviderType, typeof default> & Record<EmailProviderType, typeof default> & Record<WebAuthnProviderType, (config) => WebAuthnConfig>;

OAuthChecks

type OAuthChecks: OpenIDCallbackChecks | OAuthCallbackChecks;

OAuthConfig<Profile>

type OAuthConfig<Profile>: OIDCConfig<Profile> | OAuth2Config<Profile>;

Type parameters

Type parameter
Profile

OAuthEndpointType

type OAuthEndpointType: "authorization" | "token" | "userinfo";

OAuthProviderType

type OAuthProviderType: 
  | "42-school"
  | "apple"
  | "asgardeo"
  | "auth0"
  | "authentik"
  | "azure-ad-b2c"
  | "azure-ad"
  | "azure-devops"
  | "battlenet"
  | "beyondidentity"
  | "box"
  | "boxyhq-saml"
  | "bungie"
  | "click-up"
  | "cognito"
  | "coinbase"
  | "descope"
  | "discord"
  | "dribbble"
  | "dropbox"
  | "duende-identity-server6"
  | "eveonline"
  | "facebook"
  | "faceit"
  | "foursquare"
  | "freshbooks"
  | "fusionauth"
  | "github"
  | "gitlab"
  | "google"
  | "hubspot"
  | "identity-server4"
  | "instagram"
  | "kakao"
  | "keycloak"
  | "line"
  | "linkedin"
  | "mailchimp"
  | "mailru"
  | "mastodon"
  | "mattermost"
  | "medium"
  | "microsoft-entra-id"
  | "naver"
  | "netlify"
  | "netsuite"
  | "nodemailer"
  | "notion"
  | "okta"
  | "onelogin"
  | "ory-hydra"
  | "osso"
  | "osu"
  | "passage"
  | "passkey"
  | "patreon"
  | "pinterest"
  | "pipedrive"
  | "postmark"
  | "reddit"
  | "resend"
  | "salesforce"
  | "sendgrid"
  | "simplelogin"
  | "slack"
  | "spotify"
  | "strava"
  | "tiktok"
  | "todoist"
  | "trakt"
  | "twitch"
  | "twitter"
  | "united-effects"
  | "vk"
  | "webauthn"
  | "webex"
  | "wikimedia"
  | "wordpress"
  | "workos"
  | "yandex"
  | "zitadel"
  | "zoho"
  | "zoom";

OAuthUserConfig<Profile>

type OAuthUserConfig<Profile>: Omit<Partial<OAuthConfig<Profile>>, "options" | "type">;

Type parameters

Type parameter
Profile

OIDCConfigInternal<Profile>

type OIDCConfigInternal<Profile>: OAuthConfigInternal<Profile> & {
  checks: OIDCConfig<Profile>["checks"];
  idToken: OIDCConfig<Profile>["idToken"];
};

Type declaration

checks

checks: OIDCConfig<Profile>["checks"];

idToken

idToken: OIDCConfig<Profile>["idToken"];

Type parameters

Type parameter
Profile

OIDCUserConfig<Profile>

type OIDCUserConfig<Profile>: Omit<Partial<OIDCConfig<Profile>>, "options" | "type">;

Type parameters

Type parameter
Profile

ProfileCallback()<Profile>

type ProfileCallback<Profile>: (profile, tokens) => Awaitable<User>;

Type parameters

Type parameter
Profile

Parameters

ParameterType
profileProfile
tokensTokenSet

Returns

Awaitable<User>

Provider<P>

type Provider<P>: 
  | OIDCConfig<P>
  | OAuth2Config<P>
  | EmailConfig
  | CredentialsConfig
  | WebAuthnConfig & InternalProviderOptions | (...args) => 
  | OAuth2Config<P>
  | OIDCConfig<P>
  | EmailConfig
  | CredentialsConfig
  | WebAuthnConfig & InternalProviderOptions & InternalProviderOptions;

Must be a supported authentication provider config:

  • OAuthConfig
  • EmailConfigInternal
  • CredentialsConfigInternal

For more information, see the guides:

See

Type parameters

Type parameterValue
P extends Profileany

ProviderType

type ProviderType: 
  | "oidc"
  | "oauth"
  | "email"
  | "credentials"
  | WebAuthnProviderType;

Providers passed to Auth.js must define one of these types.

See

RedirectableProviderType

type RedirectableProviderType: "email" | "credentials";

TokenEndpointHandler

type TokenEndpointHandler: EndpointHandler<UrlParams, {
  checks: OAuthChecks;
  params: CallbackParamsType;
  }, {
  tokens: TokenSet;
}>;

UserinfoEndpointHandler

type UserinfoEndpointHandler: EndpointHandler<UrlParams, {
  tokens: TokenSet;
}, Profile>;
jwt42-school

About Auth.js

Download

Acknowledgements

Auth.js © Balázs Orbán and Team - 2024