Auth.js · Enum

session event

The Auth.js session event is an asynchronous notification hook for session activity. Use it for side effects such as audit logging; its message varies with the authentication flow and session strategy.

How it works

The session event is an asynchronous handler invoked when Auth.js processes a session event. It receives a message whose contents depend on the authentication flow and session strategy, so it is suitable for audit logging rather than changing the response.

Syntax

events: { session: (message) => Awaitable<void> }

Parameters

Name	Type	Description
`message`	`object`	Event message whose fields depend on the authentication flow and session strategy; it can include a user, JWT contents, or an adapter session.

Returns

Awaitable<void>; the event does not return a response.

Key points

The documented session-event type accepts one message and may complete synchronously or asynchronously.
Use this event for recording session activity or other non-response side effects.
Auth.js lets the configuration provide a dedicated handler for the session event alongside other event handlers.
The payload commonly carries user information, token contents, or both.
JWT-based sessions expose the session token through the message's token field.
Database-persisted sessions expose the adapter session through the message's session field.

Common mistakes

Do not use the handler to modify or return a session response; it is an event sink.
Treat the message shape as flow-dependent instead of assuming every authentication method supplies identical fields.

Example: Register a session event handler

import NextAuth from "next-auth";

export const { handlers, auth } = NextAuth({
  providers: [],
  events: {
    async session(message) {
      console.log("Session event", message);
    },
  },
});

Registers an asynchronous handler that can record session activity for auditing.

When to use it

Audit logging

Record session activity for compliance or security investigations.

Authentication debugging

Capture session-related details for operational diagnostics.

Event-driven observability

Send session activity to an internal monitoring or analytics pipeline.

Interview questions

QWhat is the purpose of the Auth.js session event?

The session event is configured under the Auth.js events option as an asynchronous function receiving a message. It runs when a session event occurs and is intended for side effects such as audit logging, not for returning a response.

Follow-up: How should the handler be designed for different session strategies? Inspect the message according to the configured flow because it may contain a JWT token or an adapter-backed session object.

QWhat does the session event handler return?

Its signature is (message) => Awaitable<void>. The callback does not produce a response; it receives event information and completes asynchronously.

Follow-up: What if application code needs to alter data exposed in the session? That is a different concern from this event handler and should use the appropriate session configuration callback.

QWhat can the session event message contain?

The message depends on the authentication flow, including whether the application uses OAuth or email authentication and JWT or database sessions. It typically contains a user and/or token-related information.

Follow-up: Which session-specific values can appear? With JWT sessions the message can contain token; with database-persisted sessions it can contain session from the adapter.

events
signIn event
signOut event
createUser event
linkAccount event
updateUser event
JWT sessions
database sessions

Source: auth/core | Auth.js. Checked 2026-10-15.