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/coreYou 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
Pick<JWTDecodeParams,"salt"|"secret">
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
logger?
optional logger: LoggerInstance | Console;raw?
optional raw: R;getToken() will return the raw JWT if this is set to true
Default
falsereq
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
Extends
Record<string,unknown>.DefaultJWT
Properties
email?
optional email: null | string;Inherited from
exp?
optional exp: number;Inherited from
iat?
optional iat: number;Inherited from
jti?
optional jti: string;Inherited from
name?
optional name: null | string;Inherited from
picture?
optional picture: null | string;Inherited from
sub?
optional sub: string;Inherited from
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 dayssalt
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
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 daysdecode()
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>