Issue an Auth.js JWT
Create the session token Auth.js will issue after authentication.
Auth.js · Function
encode
encode asynchronously issues an Auth.js JWT from JWTEncodeParams. By default, the JWT is encrypted with A256CBC-HS512 using a key derived from the configured or supplied secret.
How it works
encode asynchronously creates an Auth.js JWT from the supplied encoding parameters. Unless customized, Auth.js encrypts the JWT with A256CBC-HS512, deriving the encryption key from the provided secret.
Syntax
function encode<Payload>(params): Promise<string>Parameters
| Name | Type | Description |
|---|---|---|
params | JWTEncodeParams<Payload> | Encoding options, including the token payload and secret used for JWT processing. |
Returns
Promise<string> containing the issued JWT.
Key points
- Calling
encodeproduces an Auth.js JWT string asynchronously. - The function is generic over the payload and resolves to a string.
- Its single argument is a
JWTEncodeParamsobject parameterized by the payload type. - Auth.js protects its issued JWTs with encryption by default rather than leaving the payload merely encoded.
Common mistakes
- Do not assume the output is a signed-only token: the default encoding uses JWT encryption with A256CBC-HS512.
- Provide a secret explicitly or configure AUTH_SECRET so Auth.js can derive the encryption key.
Example: Encode a JWT
import { encode } from "@auth/core/jwt"
const token = await encode({
token: { sub: "user_123", role: "admin" },
secret: process.env.AUTH_SECRET!,
})
console.log(token)Creates an Auth.js JWT from a payload and secret, then prints the resulting encoded token.
When to use it
Encode typed claims
Use a custom payload type for application-specific claims.
Customize JWT encoding
Replace the default JWT serialization or protection behavior.
Interview questions
QWhat does encode accept and return?
encode accepts JWTEncodeParams<Payload> and returns Promise<string>. Its purpose is to issue an Auth.js JWT.
Follow-up: What is the default protection mode? The resulting JWT is encrypted with A256CBC-HS512 unless the encoding behavior is overridden.
QWhat role does the Payload type parameter play?
The generic payload type defaults to JWT, allowing callers to describe a more specific payload type when invoking the function. The encoded result remains a promise of a string.
Follow-up: How would you preserve type safety for application claims? Supply a payload type that includes those claims and pass a matching token object in the parameters.
QWhy might an application override encode?
The function is an overridable encoding hook for Auth.js-issued JWTs. Replacing it lets an application control how those JWTs are encoded.
Follow-up: What should be checked when overriding it? The replacement must honor the expected parameters and produce an awaitable string compatible with Auth.js.
Related
JWTEncodeParamsJWTdecodeA256CBC-HS512AUTH_SECRET