Carry custom claims
Persisting application identity data such as a user ID across requests.
Auth.js · Function
jwt callback
The jwt callback runs when Auth.js creates or updates a JSON Web Token. Return the token, optionally with custom claims; use the session callback to explicitly expose selected claims to the client.
How it works
The jwt callback receives token data during sign-in and later token updates. Return the token, optionally enriched with application data; Auth.js stores the returned value in the encrypted JWT and passes it to the session callback, which must explicitly expose selected fields to the client.
Syntax
jwt: (params) => Awaitable<null | JWT>Parameters
| Name | Type | Description |
|---|---|---|
params | object | Callback context containing token and, depending on the event, user, account, profile, trigger, or session data. |
Returns
Awaitable<null | JWT>
Key points
- It runs when Auth.js creates a token during sign-in.
- Client-side session access can cause the token to be updated and the callback to run again.
- Returning an enriched token persists those values and makes them available to session processing.
- Use the session callback as the boundary for selecting token data that the client receives.
- JWT callbacks can support authorization decisions without storing session state in a database.
Common mistakes
- Adding a property to the JWT does not automatically expose it to the client; copy it explicitly in the session callback.
- During sign-in or sign-up, token may contain only a subset of its eventual fields, so conditional handling may be needed.
- Keep AUTH_SECRET configured because it supplies the default encryption basis for the JWT.
Example: Persist a user ID in the JWT
import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"
export const { handlers, auth } = NextAuth({
providers: [GitHub],
callbacks: {
jwt({ token, user }) {
if (user) token.id = user.id
return token
},
session({ session, token }) {
session.user.id = token.id
return session
},
},
})The callback stores the signed-in user ID in the token; the session callback then copies it to the client-visible session.
When to use it
Database-free access control
Making authorization decisions from token claims without a session database.
Integrate external APIs
Passing provider credentials through Auth.js session handling to server-side backend requests.
Interview questions
QWhen does the jwt callback execute, and what happens to its return value?
It runs when Auth.js creates a JWT at sign-in and when the token is updated, including when a client session is accessed. The returned value is stored in the JWT and forwarded to the session callback.
Follow-up: How would you expose a custom token field to the browser? Return it from jwt, then explicitly assign token.field to a session property in session.
QHow does the token parameter differ on initial and subsequent calls?
The token parameter is a subset of the JWT during sign-in or sign-up, including name, email, and image; on later calls it is the full JWT. The callback may return null or a JWT asynchronously.
Follow-up: Why should code distinguish initial sign-in from later calls? Initial calls can include user or account data, while later calls generally rely on the persisted token.
QWhat security and storage characteristics apply to Auth.js JWT sessions?
JWTs are encrypted by default, and the callback can support access control without a database by persisting claims in the token. Auth.js derives encryption from AUTH_SECRET unless configuration supplies another secret.
Follow-up: What should be done for a third-party API that needs JWT authentication? Use the identity provider's JWT rather than treating an Auth.js JWT as a general-purpose third-party token.
Related
session callbackJWTAUTH_SECRETAuthConfig.adaptertrigger