Inspect authenticated token claims
Read claims from an Auth.js JWT on the server after obtaining the token and required decoding configuration.
Auth.js · Function
decode
decode asynchronously decodes an Auth.js-issued JWT. It returns the decoded payload or null, and supports a generic payload type.
How it works
Call decode with JWT decoding parameters, typically the token and secret. It asynchronously returns either the decoded payload or null when decoding does not produce a payload; the generic type can describe a custom payload shape.
Syntax
function decode<Payload>(params): Promise<null | Payload>Parameters
| Name | Type | Description |
|---|---|---|
params | JWTDecodeParams | Object containing the inputs required to decode the token. |
Returns
Promise<null | Payload>
Key points
- The function is generic, so callers can specify the expected decoded payload type.
- The generic payload type defaults to Auth.js's
JWTtype when no custom type is supplied. - Because decoding is asynchronous, callers must await the result before using it.
- The operation targets JWTs generated for Auth.js.
Common mistakes
- The function is intended for JWTs issued by Auth.js, not arbitrary JWT formats.
- When configuring a custom decoder, replace the default implementation consistently wherever Auth.js encodes or decodes tokens.
Example: Decode an Auth.js JWT
import { decode } from "@auth/core/jwt"
const payload = await decode({
token: process.env.AUTH_TOKEN,
secret: process.env.AUTH_SECRET,
})
if (payload) {
console.log(payload.sub)
}Decodes an Auth.js JWT and uses the returned payload when decoding succeeds.
When to use it
Type custom claims
Supply a custom payload type when application-specific JWT claims are known.
Customize token decoding
Replace the default JWT decoding behavior through Auth.js configuration.
Interview questions
QWhat does decode return?
decode accepts a JWTDecodeParams object and returns Promise<null | Payload>. Its purpose is to decode an Auth.js-issued JWT, with Payload defaulting to JWT.
Follow-up: How should a caller handle failure? Check whether the promise resolves to null before reading payload fields.
QWhat parameter does decode accept?
The required argument is the params object, whose type is JWTDecodeParams. The object supplies the information needed by the Auth.js JWT decoder.
Follow-up: What is the advantage of passing a parameter object? It keeps the API extensible and makes each decoding input explicit.
QWhen would you override the decoder?
Auth.js exposes a configurable decode method that can be overridden to control how issued JWTs are decoded. A custom implementation must remain compatible with the expected asynchronous result and payload contract.
Follow-up: What contract must a replacement preserve? It should accept the configured decode parameters and resolve to either a payload or null.
Related
JWTDecodeParamsJWTencode