adapters

Adapter

An adapter is an object with function properties (methods) that read and write data from a data source. Think of these methods as a way to normalize the data layer to common interfaces that Auth.js can understand.

This is what makes Auth.js very flexible and allows it to be used with any data layer.

The adapter methods are used to perform the following operations:

Create/update/delete a user
Link/unlink an account to/from a user
Handle active sessions
Support passwordless authentication across multiple devices

If any of the methods are not implemented, but are called by Auth.js, an error will be shown to the user and the operation will fail.

Methods

createAuthenticator()?

optional createAuthenticator(authenticator): Awaitable<AdapterAuthenticator>

Create a new authenticator.

If the creation fails, the adapter must throw an error.

Parameters

Parameter	Type
`authenticator`	`AdapterAuthenticator`

Returns

Awaitable<AdapterAuthenticator>

createSession()?

optional createSession(session): Awaitable<AdapterSession>

Creates a session for the user and returns it.

See also Database Session management

Parameters

Parameter	Type
`session`	`Object`
`session.expires`	`Date`
`session.sessionToken`	`string`
`session.userId`	`string`

Returns

Awaitable<AdapterSession>

createUser()?

optional createUser(user): Awaitable<AdapterUser>

Creates a user in the database and returns it.

See also User management

Parameters

Parameter	Type
`user`	`AdapterUser`

Returns

Awaitable<AdapterUser>

createVerificationToken()?

optional createVerificationToken(verificationToken): Awaitable<undefined | null | VerificationToken>

Creates a verification token and returns it.

Parameters

Parameter	Type
`verificationToken`	`VerificationToken`

Returns

Awaitable<undefined | null | VerificationToken>

deleteSession()?

optional deleteSession(sessionToken): Promise<void> | Awaitable<undefined | null | AdapterSession>

Deletes a session from the database. It is preferred that this method also returns the session that is being deleted for logging purposes.

See also Database Session management

Parameters

Parameter	Type
`sessionToken`	`string`

Returns

Promise<void> | Awaitable<undefined | null | AdapterSession>

deleteUser()?

optional deleteUser(userId): Promise<void> | Awaitable<undefined | null | AdapterUser>

Parameters

Parameter	Type
`userId`	`string`

Returns

Promise<void> | Awaitable<undefined | null | AdapterUser>

Todo

This method is currently not invoked yet.

See also User management

getAccount()?

optional getAccount(providerAccountId, provider): Awaitable<null | AdapterAccount>

Get account by provider account id and provider.

If an account is not found, the adapter must return null.

Parameters

Parameter	Type
`providerAccountId`	`string`
`provider`	`string`

Returns

Awaitable<null | AdapterAccount>

getAuthenticator()?

optional getAuthenticator(credentialID): Awaitable<null | AdapterAuthenticator>

Returns an authenticator from its credentialID.

If an authenticator is not found, the adapter must return null.

Parameters

Parameter	Type
`credentialID`	`string`

Returns

Awaitable<null | AdapterAuthenticator>

getSessionAndUser()?

optional getSessionAndUser(sessionToken): Awaitable<null | {
  session: AdapterSession;
  user: AdapterUser;
}>

Returns a session and a userfrom the database in one go.

💡

If the database supports joins, it’s recommended to reduce the number of database queries.

See also Database Session management

Parameters

Parameter	Type
`sessionToken`	`string`

Returns

Awaitable<null | { session: AdapterSession; user: AdapterUser; }>

getUser()?

optional getUser(id): Awaitable<null | AdapterUser>

Returns a user from the database via the user id.

See also User management

Parameters

Parameter	Type
`id`	`string`

Returns

Awaitable<null | AdapterUser>

getUserByAccount()?

optional getUserByAccount(providerAccountId): Awaitable<null | AdapterUser>

Using the provider id and the id of the user for a specific account, get the user.

See also User management

Parameters

Parameter	Type
`providerAccountId`	`Pick`<`AdapterAccount`, `"provider"` \| `"providerAccountId"`>

Returns

Awaitable<null | AdapterUser>

getUserByEmail()?

optional getUserByEmail(email): Awaitable<null | AdapterUser>

Returns a user from the database via the user’s email address.

Parameters

Parameter	Type
`email`	`string`

Returns

Awaitable<null | AdapterUser>

linkAccount()?

optional linkAccount(account): Promise<void> | Awaitable<undefined | null | AdapterAccount>

This method is invoked internally (but optionally can be used for manual linking). It creates an Account in the database.

See also User management

Parameters

Parameter	Type
`account`	`AdapterAccount`

Returns

Promise<void> | Awaitable<undefined | null | AdapterAccount>

listAuthenticatorsByUserId()?

optional listAuthenticatorsByUserId(userId): Awaitable<AdapterAuthenticator[]>

Returns all authenticators from a user.

If a user is not found, the adapter should still return an empty array. If the retrieval fails for some other reason, the adapter must throw an error.

Parameters

Parameter	Type
`userId`	`string`

Returns

Awaitable<AdapterAuthenticator[]>

unlinkAccount()?

optional unlinkAccount(providerAccountId): Promise<void> | Awaitable<undefined | AdapterAccount>

Parameters

Parameter	Type
`providerAccountId`	`Pick`<`AdapterAccount`, `"provider"` \| `"providerAccountId"`>

Returns

Promise<void> | Awaitable<undefined | AdapterAccount>

Todo

This method is currently not invoked yet.

updateAuthenticatorCounter()?

optional updateAuthenticatorCounter(credentialID, newCounter): Awaitable<AdapterAuthenticator>

Updates an authenticator’s counter.

If the update fails, the adapter must throw an error.

Parameters

Parameter	Type
`credentialID`	`string`
`newCounter`	`number`

Returns

Awaitable<AdapterAuthenticator>

updateSession()?

optional updateSession(session): Awaitable<undefined | null | AdapterSession>

Updates a session in the database and returns it.

See also Database Session management

Parameters

Parameter	Type
`session`	`Partial`<`AdapterSession`> & `Pick`<`AdapterSession`, `"sessionToken"`>

Returns

Awaitable<undefined | null | AdapterSession>

updateUser()?

optional updateUser(user): Awaitable<AdapterUser>

Updates a user in the database and returns it.

See also User management

Parameters

Parameter	Type
`user`	`Partial`<`AdapterUser`> & `Pick`<`AdapterUser`, `"id"`>

Returns

Awaitable<AdapterUser>

useVerificationToken()?

optional useVerificationToken(params): Awaitable<null | VerificationToken>

Return verification token from the database and deletes it so it can only be used once.

Parameters

Parameter	Type
`params`	`Object`
`params.identifier`	`string`
`params.token`	`string`

Returns

Awaitable<null | VerificationToken>

AdapterAccount

An account is a connection between a user and a provider.

There are two types of accounts:

OAuth/OIDC accounts, which are created when a user signs in with an OAuth provider.
Email accounts, which are created when a user signs in with an Email provider.

One user can have multiple accounts.

Extends

Account

Properties

access_token?

optional readonly access_token: string;

Inherited from

Account.access_token

authorization_details?

optional readonly authorization_details: AuthorizationDetails[];

Inherited from

Account.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

Inherited from

Account.expires_at

expires_in?

optional readonly expires_in: number;

Inherited from

Account.expires_in

id_token?

optional readonly id_token: string;

Inherited from

Account.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

Inherited from

Account.provider

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

Inherited from

Account.providerAccountId

refresh_token?

optional readonly refresh_token: string;

Inherited from

Account.refresh_token

scope?

optional readonly scope: string;

Inherited from

Account.scope

token_type?

optional readonly token_type: Lowercase<string>;

NOTE: because the value is case insensitive it is always returned lowercased

Inherited from

Account.token_type

type

type: AdapterAccountType;

Provider’s type for this account

Overrides

Account.type

userId

userId: string;

id of the user this account belongs to

See

https://authjs.dev/reference/core/adapters#adapteruser

Overrides

Account.userId

AdapterAuthenticator

An authenticator represents a credential authenticator assigned to a user.

Extends

Authenticator

Properties

counter

counter: number;

Number of times the authenticator has been used.

Inherited from

Authenticator.counter

credentialBackedUp

credentialBackedUp: boolean;

Whether the client authenticator backed up the credential.

Inherited from

Authenticator.credentialBackedUp

credentialDeviceType

credentialDeviceType: string;

Device type of the authenticator.

Inherited from

Authenticator.credentialDeviceType

credentialID

credentialID: string;

Base64 encoded credential ID.

Inherited from

Authenticator.credentialID

credentialPublicKey

credentialPublicKey: string;

Base64 encoded credential public key.

Inherited from

Authenticator.credentialPublicKey

providerAccountId

providerAccountId: string;

The provider account ID connected to the authenticator.

Inherited from

Authenticator.providerAccountId

transports?

optional transports: null | string;

Concatenated transport flags.

Inherited from

Authenticator.transports

userId

userId: string;

User ID of the authenticator.

Overrides

Authenticator.userId

AdapterSession

A session holds information about a user’s current signin state.

Properties

expires

expires: Date;

The absolute date when the session expires.

If a session is accessed prior to its expiry date, it will be extended based on the maxAge option as defined in by SessionOptions.maxAge. It is never extended more than once in a period defined by SessionOptions.updateAge.

If a session is accessed past its expiry date, it will be removed from the database to clean up inactive sessions.

sessionToken

sessionToken: string;

A randomly generated value that is used to look up the session in the database when using "database" AuthConfig.strategy option. This value is saved in a secure, HTTP-Only cookie on the client.

userId

userId: string;

Connects the active session to a user in the database

AdapterUser

A user represents a person who can sign in to the application. If a user does not exist yet, it will be created when they sign in for the first time, using the information (profile data) returned by the identity provider. A corresponding account is also created and linked to the user.

Extends

User

Properties

email

email: string;

The user’s email address.

Overrides

User.email

emailVerified

emailVerified: null | Date;

Whether the user has verified their email address via an Email provider. It is null if the user has not signed in with the Email provider yet, or the date of the first successful signin.

id

id: string;

A unique identifier for the user.

Overrides

User.id

image?

optional image: null | string;

Inherited from

User.image

name?

optional name: null | string;

Inherited from

User.name

VerificationToken

A verification token is a temporary token that is used to sign in a user via their email address. It is created when a user signs in with an Email provider. When the user clicks the link in the email, the token and email is sent back to the server where it is hashed and compared to the value in the database. If the tokens and emails match, and the token hasn’t expired yet, the user is signed in. The token is then deleted from the database.

Properties

expires

expires: Date;

The absolute date when the token expires.

identifier

identifier: string;

The user’s email address.

token

token: string;

A hashed token, using the AuthConfig.secret value.

AdapterAccountType

type AdapterAccountType: Extract<ProviderType, "oauth" | "oidc" | "email" | "webauthn">;

The type of account.

isDate()

isDate(value): value is string

Determines if a given value can be parsed into Date

Parameters

Parameter	Type
`value`	`unknown`

Returns

value is string

@auth/express lib