adapters

This module contains functions and types that a database adapter can use to be compatible with Auth.js.

A database adapter provides a common interface for Auth.js so that it can work with any database/ORM adapter without concerning itself with the implementation details of the database/ORM.

Auth.js supports 2 session strtategies to persist the login state of a user. The default is to use a cookie + JWT based session store (strategy: "jwt"), but you can also use a database adapter to store the session in a database.

Note

Auth.js currently does not implement federated logout. So even if the session is deleted from the database, the user will still be logged in to the provider (but will be logged out of the app). See this discussion for more information.

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/adapters.

Usage

Built-in adapters already implement this interfac, so you likely won't need to implement it yourself. If you do, you can use the following example as a starting point.

your-adapter.ts

import { type Adapter } from "@auth/core/adapters"

export function MyAdapter(config: {}): Adapter {
 // implement the adapter methods
}

index.ts

import { MyAdapter } from "./your-adapter"

const response = Auth({
  adapter: MyAdapter({ /* ...adapter config */ }),
  // ... auth config
})

Note

Although @auth/core is framework/runtime agnostic, an adapter might rely on a client/ORM package, that is not yet compatible with your runtime (E.g. it might rely on Node.js-specific APIs) when you are trying to use it elsewhere. Related issues should be reported to the corresponding package maintainers.

Testing

tip

If you are writing your own adapter, there is a test suite available to ensure that your adapter is compatible with Auth.js.

Resources

• What is a database session strategy?

Interfaces

Adapter

Using a custom adapter you can connect to any database backend or even several different databases. Custom adapters created and maintained by our community can be found in the adapters repository. Feel free to add a custom adapter from your project to the repository, or even become a maintainer of a certain adapter. Custom adapters can still be created and used in a project without being added to the repository.

Resources

• Session strategies
• Using a database adapter
• Creating a database adapter

Methods

createSession()

Signature

createSession(session: Object): Awaitable<AdapterSession>

Creates a session for the user and returns it.

Parameters

Name	Type
session	Object
session.expires	Date
session.sessionToken	string
session.userId	string

Returns

Awaitable<AdapterSession>

deleteSession()

Signature

deleteSession(sessionToken: string): 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.

Parameters

Name	Type
sessionToken	string

Returns

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

getUserByAccount()

Signature

getUserByAccount(providerAccountId: Pick<AdapterAccount, "provider" | "providerAccountId">): Awaitable<null | AdapterUser>

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

Parameters

Name	Type
providerAccountId	Pick<AdapterAccount, "provider" | "providerAccountId">

Returns

Awaitable<null | AdapterUser>

deleteUser()

Signature

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

Todo

This method is currently not implemented. Defining it will have no effect

Parameters

Name	Type
userId	string

Returns

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

unlinkAccount()

Signature

Optional unlinkAccount(providerAccountId: Pick<AdapterAccount, "provider" | "providerAccountId">): Promise<void> | Awaitable<undefined | AdapterAccount>

Todo

This method is currently not implemented. Defining it will have no effect

Parameters

Name	Type
providerAccountId	Pick<AdapterAccount, "provider" | "providerAccountId">

Returns

Promise<void> | Awaitable<undefined | AdapterAccount>

useVerificationToken()

Signature

Optional useVerificationToken(params: Object): Awaitable<null | VerificationToken>

Return verification token from the database and delete it so it cannot be used again.

Parameters

Name	Type
params	Object
params.identifier	string
params.token	string

Returns

Awaitable<null | VerificationToken>

---

AdapterSession

The session object implementing this interface is used to look up the user in the database.

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 get hold of the session.

userId

userId: string

Connects the active session to a user in the database