Audit sign-ins and sign-outs
Security monitoring
Auth.js · Pipe
events
Auth.js events are optional asynchronous lifecycle handlers for side effects such as audit logging. They observe authentication activity without returning an authentication response.
How it works
The optional events configuration maps authentication lifecycle event names to asynchronous handlers. Handlers receive an event-specific message, perform side effects such as audit logging, and do not produce an authentication response.
Syntax
events: { createUser?: (message) => Awaitable<void>; linkAccount?: (message) => Awaitable<void>; session?: (message) => Awaitable<void>; signIn?: (message) => Awaitable<void>; signOut?: (message) => Awaitable<void>; updateUser?: (message) => Awaitable<void>; }Parameters
| Name | Type | Description |
|---|---|---|
events | { createUser?: (message) => Awaitable<void>; linkAccount?: (message) => Awaitable<void>; session?: (message) => Awaitable<void>; signIn?: (message) => Awaitable<void>; signOut?: (message) => Awaitable | Optional lifecycle handlers: createUser, linkAccount, session, signIn, signOut, and updateUser; each accepts a message and returns Awaitable<void>. |
Returns
Event handlers return Awaitable<void>; the events configuration itself does not return an authentication response.
Key points
- Use events for side effects rather than changing redirects, sessions, or authorization results.
- A common application is recording authentication activity for security review and compliance.
- Handlers are optional, so configure only the lifecycle events the application needs.
- Event payloads may expose identity data or token data for the operation being observed.
Common mistakes
- Do not assume every event message has the same shape; its contents depend on the authentication and session flow.
Example: Register a sign-in event
import NextAuth from "next-auth";
export const { handlers, auth } = NextAuth({
providers: [],
events: {
async signIn({ user }) {
console.log("Signed in:", user.email);
},
},
});This registers an asynchronous sign-in event handler that can be replaced with audit-log persistence.
When to use it
Record user creation and account linking
Account lifecycle tracking
Track session activity
Operational observability
Interview questions
QWhat is the purpose of Auth.js events?
Events are asynchronous handlers configured under events. Unlike callbacks, they do not return a response and are intended for side effects such as audit logging.
Follow-up: What should an event handler do with its message? Inspect it according to the specific event and flow, because the message shape is not uniform.
QWhich event handlers are available?
The documented event names are createUser, linkAccount, session, signIn, signOut, and updateUser. Each handler receives a message and resolves to void.
Follow-up: How would you record a sign-out? Add an asynchronous signOut handler and persist the relevant event details to an audit system.
QWhat can an event message contain?
The message commonly contains a user object and/or JWT contents, but the exact data depends on whether the flow uses OAuth or email authentication and JWT or database sessions.
Follow-up: Why must code branch defensively? The same event name can receive different message contents across authentication and session configurations.
Related
callbackscreateUserlinkAccountsessionsignInsignOutupdateUserEventError