Auth.js · Pipe

jwt

Auth.js JWT utilities encode and decode the encrypted JWTs used by Auth.js. They use AUTH_SECRET or an explicit secret and are intended primarily for the app that issued them.

How it works

The @auth/core/jwt module provides helpers for issuing and reading Auth.js JWTs. Tokens are encrypted by default with A256CBC-HS512, using AUTH_SECRET or a supplied secret; they are intended for the application that created them rather than as general-purpose third-party API tokens.

Syntax

encode<Payload>(params): Promise<string>
decode<Payload>(params): Promise<null | Payload>
getToken<R>(params): Promise<R extends true ? string : null | JWT>

Returns

encode returns a JWT string; decode returns the decoded payload or null; getToken returns the payload or raw JWT, and returns null when no usable token is found.

Key points

The default protection is authenticated encryption with the A256CBC-HS512 JWE algorithm.
The encryption key material comes from the environment secret or an explicitly supplied secret.
encode returns a newly issued encrypted token rather than a plaintext payload.
decode reads an Auth.js token and resolves its payload when the token and secret are valid.
getToken can return structured claims or the original compact token, depending on its options.

Common mistakes

Do not use Auth.js JWTs as a general authentication format for unrelated third-party APIs; use the identity provider's token instead.
Treat the token as an encrypted JWE rather than assuming it is merely a signed, readable JWT.
When retrieving a token from a request, account for both cookie and Authorization-header sources.

Example: Encode and decode an Auth.js JWT

import { encode, decode } from "@auth/core/jwt"

const secret = process.env.AUTH_SECRET!
const token = await encode({
  token: { sub: "user-123", role: "admin" },
  secret,
})
const payload = await decode({ token, secret })
console.log(payload?.role)

This creates an encrypted Auth.js JWT and then decodes it with the same secret.

When to use it

Issue or inspect an Auth.js JWT

Custom server-side token handling

Extract a token from cookies or an Authorization header

Request authentication

Read encrypted JWT payload data inside the issuing application

Claim processing

Interview questions

QWhat do the Auth.js JWT helpers do?

The module exposes encode to issue a JWT and decode to read an Auth.js-issued JWT. Auth.js encrypts the JWT by default with A256CBC-HS512, deriving the key from the configured secret.

Follow-up: Why should an Auth.js JWT not normally be sent to an unrelated API? It is designed for use by the application that issued it, so an identity-provider access token is the appropriate credential for a third-party API.

QHow does Auth.js retrieve a JWT from a request?

getToken accepts an Auth.js request and returns either the decoded payload or, when requested, the raw JWT string. It searches cookies and the Authorization header for the token.

Follow-up: What happens when no usable token is found? The function returns null, including when a Bearer value has malformed percent-encoding.

QHow is an Auth.js JWT protected?

The secret can come from the AUTH_SECRET environment variable or from the secret parameter passed to the helper. That secret is used to derive the encryption key for the token.

Follow-up: What deployment requirement follows from this? The application must provide a cryptographically secure AUTH_SECRET; the deployment documentation recommends a random value of at least 32 characters.

encode
decode
getToken
JWT
AUTH_SECRET
session.strategy

Source: Jwt - Auth.js. Checked 2026-10-15.

jwt