Copy selected claims from `token` into the client session
JWT session strategy
Auth.js · Function
session callback
The session callback customizes the session object returned to the client whenever Auth.js checks a session. Use it to expose selected JWT or database-user data, while avoiding sensitive fields.
How it works
The session callback receives session data plus strategy-dependent values, lets you add or change properties, and must return the session object. Values added to a JWT are not client-visible until this callback explicitly includes them; with database sessions, use the supplied user instead.
Syntax
session: (params) => Awaitable<Session | DefaultSession>Parameters
| Name | Type | Description |
|---|---|---|
params | object | The callback parameter object; it includes session, and strategy-dependent token or user values. |
session | Session | The current session object to customize and return. |
token | JWT | The JWT payload, available with the JWT session strategy. |
user | AdapterUser | The database user, available with the database session strategy. |
Returns
Awaitable<Session | DefaultSession>
Key points
- Auth.js invokes it during session checks, including common client and server session access paths.
- The object returned from the callback defines the client-visible session shape.
- Auth.js intentionally limits the default token-to-session exposure.
- The callback can perform database access when session enrichment requires additional data.
- A common use is copying a database user ID into
session.user.id.
Common mistakes
- Anything returned by the callback can reach the client, so do not include secrets or other sensitive data.
- Adding a property in
jwtalone does not expose it; copy it onto the returned session. - Do not assume both
tokenanduserare available: their presence depends on the configured session strategy.
Example: Expose a user ID in the session
import NextAuth from "next-auth"
declare module "next-auth" {
interface Session {
user: { id: string } & DefaultSession["user"]
}
}
export const { handlers, auth } = NextAuth({
providers: [],
callbacks: {
session({ session, token }) {
session.user.id = token.id as string
return session
},
},
})The callback copies a value previously placed in the JWT onto the session returned to the client.
When to use it
Add user or database-derived attributes to the returned session
Database session strategy
Retrieve additional information from a database or API before returning the session
External data enrichment
Interview questions
QWhen does the session callback run, and what does it control?
It runs whenever Auth.js checks a session, such as through the session endpoint, useSession, or getSession. Its returned value is the session data exposed to the client.
Follow-up: How would you expose a value stored by the JWT callback? Return the session after copying the value from token onto the appropriate session property.
QWhich callback parameters depend on the session strategy?
With JWT sessions, the callback can receive token; with database sessions, it can receive user. The callback should return the session object, optionally enriched with approved data.
Follow-up: What changes when switching from JWT to database sessions? Replace token-based enrichment with data obtained from the user argument or a database lookup.
QWhy must the session callback explicitly return custom JWT fields?
The callback determines which session fields are sent to the client. Fields added to the JWT must be explicitly copied into the returned session, and only a subset is returned by default for security.
Follow-up: How should sensitive provider tokens be handled? Expose them only when required and validate the client-facing design because the returned session is public to the client.
Related
jwt callbackuseSessiongetSessionauth()SessionDefaultSession