Persist a user's active session
Implementing a database adapter
Auth.js · Type Alias
AdapterSession
AdapterSession is the persisted session shape used by Auth.js database adapters. It records the expiration time, lookup token, and associated user ID.
How it works
AdapterSession is the database-backed session shape used by Auth.js adapters. It ties a user to a session token and records the absolute expiry time; adapter methods can return it directly or together with the associated user.
Syntax
type AdapterSession = { expires: Date; sessionToken: string; userId: string }Parameters
| Name | Type | Description |
|---|---|---|
expires | Date | Absolute expiration time for the session. |
sessionToken | string | Token used to look up the session. |
userId | string | Identifier of the associated user. |
Returns
An AdapterSession object with expires: Date, sessionToken: string, and userId: string.
Key points
- It models the persisted state for a user's active sign-in.
- The expires field is an absolute Date marking when the session becomes invalid.
- sessionToken is the lookup identifier for the stored session and should be generated securely.
- The session token is kept in a secure, HTTP-only client cookie when database sessions are used.
- userId associates the persisted session with its database user record.
- AdapterSession can be returned alongside AdapterUser by getSessionAndUser for a combined lookup.
Common mistakes
- Reading a still-valid session can extend its lifetime according to the configured maxAge and updateAge settings.
Example: Construct an adapter session
import type { AdapterSession } from "next-auth/adapters";
const session: AdapterSession = {
sessionToken: crypto.randomUUID(),
userId: "user_123",
expires: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
};
console.log(session);This creates a value that satisfies the adapter session shape.
When to use it
Look up a session by its token
Resolving an authenticated request
Return the session together with its user
Loading authentication context
Interview questions
QWhat does AdapterSession represent, and which fields does it contain?
AdapterSession represents a persisted user session for an Auth.js adapter. Its core fields are an expiration date, a session token, and the user ID.
Follow-up: Why is the token needed? It provides the value used to find the stored session when the database strategy is active.
QHow is AdapterSession used by createSession?
An adapter's createSession method accepts a session object containing expires, sessionToken, and userId, then returns an Awaitable<AdapterSession>. This lets the adapter persist the session and provide the resulting session object.
Follow-up: What should getSessionAndUser return? It may return null, or an object containing both an AdapterSession and an AdapterUser.
QHow does AdapterSession participate in database-session lookup?
With the database strategy, the session cookie contains the sessionToken, which Auth.js uses to look up the session in the database. The stored AdapterSession supplies the associated user and expiry information.
Follow-up: How can a project avoid database session storage? Explicitly configure the JWT strategy instead of relying on the adapter-default database strategy.
Related
AdapterAdapterUsercreateSessiongetSessionAndUserupdateSessiondeleteSessionSessionOptions.maxAgeSessionOptions.updateAge