jwt

This module contains functions and types to encode and decode JWTs issued and used by Auth.js.

The JWT issued by Auth.js is encrypted by default, using the A256CBC-HS512 algorithm (JWE). It uses the AUTH_SECRET environment variable or the passed secret propery to derive a suitable encryption key.

Note Auth.js JWTs are meant to be used by the same app that issued them. If you need JWT authentication for your third-party API, you should rely on your Identity Provider instead.

Installation

npm install @auth/core

pnpm add @auth/core

yarn add @auth/core

bun add @auth/core

You can then import this submodule from @auth/core/jwt.

Usage

⚠️

Warning This module will be refactored/changed. We do not recommend relying on it right now.

Resources

DefaultJWT

Extends

Record<string, unknown>

Properties

email?

optional email: null | string;

exp?

optional exp: number;

iat?

optional iat: number;

jti?

optional jti: string;

name?

optional name: null | string;

picture?

optional picture: null | string;

sub?

optional sub: string;

GetTokenParams<R>

Extends

GetTokenParamsBase

Type parameters

Type parameter	Value
`R` extends `boolean`	`false`

Properties

cookieName?

optional cookieName: string;

If the JWT is in the cookie, what name getToken() should look for.

decode()?

optional decode: (params) => Awaitable<null | JWT>;

Parameters

Parameter	Type
`params`	`JWTDecodeParams`

Returns

Awaitable<null | JWT>

logger?

optional logger: LoggerInstance | Console;

raw?

optional raw: R;

getToken() will return the raw JWT if this is set to true

Default

false

req

req: Request | {
  headers: Record<string, string> | Headers;
};

The request containing the JWT either in the cookies or in the Authorization header.

salt?

optional salt: string;

Inherited from

GetTokenParamsBase.salt

secret

secret: string | string[];

Inherited from

GetTokenParamsBase.secret

secureCookie?

optional secureCookie: boolean;

Use secure prefix for cookie name, unless URL in NEXTAUTH_URL is http:// or not set (e.g. development or test instance) case use unprefixed name

JWT

Returned by the jwt callback when using JWT sessions

jwt callback

Extends

Record<string, unknown>.DefaultJWT

Properties

email?

optional email: null | string;

Inherited from

DefaultJWT.email

exp?

optional exp: number;

Inherited from

DefaultJWT.exp

iat?

optional iat: number;

Inherited from

DefaultJWT.iat

jti?

optional jti: string;

Inherited from

DefaultJWT.jti

name?

optional name: null | string;

Inherited from

DefaultJWT.name

picture?

optional picture: null | string;

Inherited from

DefaultJWT.picture

sub?

optional sub: string;

Inherited from

DefaultJWT.sub

JWTDecodeParams

Properties

salt

salt: string;

Used in combination with secret, to derive the encryption secret for JWTs.

secret

secret: string | string[];

Used in combination with salt, to derive the encryption secret for JWTs.

Note

You can also pass an array of secrets, in which case the first secret that successfully decrypts the JWT will be used. This is useful for rotating secrets without invalidating existing sessions. The newer secret should be added to the start of the array, which will be used for all new sessions.

token?

optional token: string;

The Auth.js issued JWT to be decoded

JWTEncodeParams<Payload>

Type parameters

Type parameter	Value
`Payload`	`JWT`

Properties

maxAge?

optional maxAge: number;

The maximum age of the Auth.js issued JWT in seconds.

Default

30 * 24 * 60 * 60 // 30 days

salt

salt: string;

Used in combination with secret, to derive the encryption secret for JWTs.

secret

secret: string | string[];

Used in combination with salt, to derive the encryption secret for JWTs.

token?

optional token: Payload;

The JWT payload.

JWTOptions

Properties

decode()

decode: (params) => Awaitable<null | JWT>;

Override this method to control the Auth.js issued JWT decoding.

Parameters

Parameter	Type
`params`	`JWTDecodeParams`

Returns

Awaitable<null | JWT>

encode()

encode: (params) => Awaitable<string>;

Override this method to control the Auth.js issued JWT encoding.

Parameters

Parameter	Type
`params`	`JWTEncodeParams`<`JWT`>

Returns

Awaitable<string>

maxAge

maxAge: number;

The maximum age of the Auth.js issued JWT in seconds.

Default

30 * 24 * 60 * 60 // 30 days

decode()

decode<Payload>(params): Promise<Payload | null>

Decodes a Auth.js issued JWT.

Type parameters

Type parameter	Value
`Payload`	`JWT`

Parameters

Parameter	Type
`params`	`JWTDecodeParams`

Returns

Promise<Payload | null>

encode()

encode<Payload>(params): Promise<string>

Issues a JWT. By default, the JWT is encrypted using “A256CBC-HS512”.

Type parameters

Type parameter	Value
`Payload`	`JWT`

Parameters

Parameter	Type
`params`	`JWTEncodeParams`<`Payload`>

Returns

Promise<string>

getToken()

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

Takes an Auth.js request (req) and returns either the Auth.js issued JWT’s payload, or the raw JWT string. We look for the JWT in the either the cookies, or the Authorization header.

Type parameters

Type parameter	Value
`R` extends `boolean`	`false`

Parameters

Parameter	Type
`params`	`GetTokenParams`<`R`>

Returns

Promise<R extends true ? string : JWT | null>

errors providers