Auth.js · Interface

JWT

Auth.js JWT utilities issue, decode, and retrieve encrypted JSON Web Tokens. They use AUTH_SECRET or a supplied secret and are intended primarily for the app that issued them.

How it works

The JWT module provides helpers to issue, decode, and retrieve Auth.js JWTs. Tokens use the configured secret and are encrypted by default; retrieval checks the request cookies or Authorization header and can return either the decoded payload or the raw token.

Syntax

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

Key points

New Auth.js JWTs are encrypted JWE values using A256CBC-HS512 unless the relevant behavior is changed.
Key material comes from AUTH_SECRET or an explicitly supplied secret option.
encode() issues a token with the documented default encryption algorithm.
getToken() searches request cookies and the Authorization header for the token.

Common mistakes

Do not treat an Auth.js JWT as a general-purpose credential for a third-party API; use the identity provider for that scenario.
getToken() does not throw merely because the request lacks a token; its no-token result is null.

Example: Encode and decode an Auth.js JWT

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

const token = await encode({
  token: { sub: "user-123" },
  secret: process.env.AUTH_SECRET!,
})

const payload = await decode({
  token,
  secret: process.env.AUTH_SECRET!,
})

console.log(payload?.sub)

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

When to use it

Issue a JWT

A server needs to create an Auth.js-compatible session token using the configured application secret.

Decode a token

Application code needs to inspect claims from a token previously issued by Auth.js.

Read a request token

A request handler needs to obtain the session token from browser cookies or a bearer header.

Interview questions

QWhat does the Auth.js JWT module provide?

The module exposes encode(), decode(), and getToken(). encode() issues a JWT, decode() parses an Auth.js-issued token, and getToken() extracts a payload or raw token from a request.

Follow-up: Where does getToken() search? It checks cookies and the Authorization header.

QHow are Auth.js JWTs protected by default?

Auth.js encrypts its JWTs by default with the A256CBC-HS512 algorithm. The encryption key is derived from AUTH_SECRET or from the secret supplied to the helper.

Follow-up: What should be configured consistently between issuing and decoding? The same effective secret must be available.

QHow does getToken() behave when reading a request?

getToken() accepts an Auth.js request and returns the decoded payload by default, or the raw JWT when configured for a raw result. If no token is present, it returns null.

Follow-up: What other failure case is documented? A malformed percent-encoded Bearer value also produces null.

encode()
decode()
getToken()
JWT
GetTokenParams
JWTOptions

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

JWT