Skip to content
Migrating from NextAuth.js v4? Read our migration guide.
API reference
jwt

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

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

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

Type parameters

Type parameterValue
R extends booleanfalse

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
ParameterType
paramsJWTDecodeParams
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

salt: string;

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

Inherited from

Pick.salt

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.

Inherited from

Pick.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

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 parameterValue
PayloadJWT

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
ParameterType
paramsJWTDecodeParams
Returns

Awaitable<null | JWT>

encode()

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

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

Parameters
ParameterType
paramsJWTEncodeParams<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 parameterValue
PayloadJWT

Parameters

ParameterType
paramsJWTDecodeParams

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 parameterValue
PayloadJWT

Parameters

ParameterType
paramsJWTEncodeParams<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 parameterValue
R extends booleanfalse

Parameters

ParameterType
paramsGetTokenParams<R>

Returns

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

Auth.js © Balázs Orbán and Team - 2024