Azion `JWT` library

The JWT Library provides utility functions for signing, verifying, and decoding JSON Web Tokens (JWTs). This library ensures ease of use and security when handling JWTs in web applications.

Go to Azion Libraries Overview

Usage

`sign`

Signs a JWT payload with the specified algorithm and private key.

Example:

import { sign } from 'azion/jwt';
import type { JWTPayload } from 'azion/jwt';

const privateKey: string = 'your-private-key';
const payload: JWTPayload = { userId: 123, exp: Math.floor(Date.now() / 1000) + 3600 }; // 1 hour expiration
sign(payload, privateKey).then((token: string) => console.log(token)); // Outputs the signed JWT

Parameters:

Parameter	Type	Description
`payload`	`JWTPayload`	The payload to be signed.
`privateKey`	`SignatureKey`	The private key used for signing.
`alg`	`SignatureAlgorithm`	The algorithm to use for signing. Default: `'HS256'`.

Returns:

Return Type	Description
`Promise<string>`	The signed JWT.

`verify`

Verifies a JWT using the specified public key and algorithm.

Example:

import { verify } from 'azion/jwt';
import type { JWTPayload } from 'azion/jwt';

const publicKey: string = 'your-public-key';
const token: string = 'your-jwt-token';
verify(token, publicKey)
  .then((payload: JWTPayload) => console.log(payload))
  .catch((err) => console.error(err)); // Outputs the payload if verification is successful

Parameters:

Parameter	Type	Description
`token`	`string`	The JWT to verify.
`publicKey`	`SignatureKey`	The public key used for verification.
`alg`	`SignatureAlgorithm` (optional)	The algorithm to be used for the verification. Default: `'HS256'`.

Returns:

Return Type	Description
`Promise<JWTPayload>`	The decoded payload if the token is valid.

`decode`

Decodes a JWT without verifying its signature.

import { decode } from 'azion/jwt';
import type { JWTPayload, TokenHeader } from 'azion/jwt';

const token: string = 'your-jwt-token';
const { header, payload }: { header: TokenHeader; payload: JWTPayload } = decode(token);
console.log(header, payload); // Outputs the decoded header and payload

Parameters:

Parameter	Type	Description
`token`	`string`	The JWT to decode.

Returns:

Return Type	Description
`{ header: TokenHeader; payload: JWTPayload }`	The decoded header and payload.

Types

The following types define the structure of the data used in the JWT Library.

`JWTPayload`

Defines the structure of the JWT payload.

type JWTPayload = {
  [key: string]: unknown;
  exp?: number;
  nbf?: number;
  iat?: number;
};

Parameters:

Parameter	Type	Description
`key`	`string`	A custom key-value pair in the payload.
`exp`	`number`	The expiration time of the token, in seconds.
`nbf`	`number`	The time before which the token isn’t valid.
`iat`	`number`	The time when the token was issued, in seconds.

`TokenHeader`

Defines the structure of the JWT header.

interface TokenHeader {
  alg: SignatureAlgorithm;
  typ?: 'JWT';
}

Parameters:

Parameter	Type	Description
`alg`	`SignatureAlgorithm`	The algorithm used to sign the JWT.
`typ`	`string` (optional)	The type of the token, typically ‘JWT’.

Errors

These are the types of errors that may be returned by the library methods.

`JwtAlgorithmNotImplemented`

Thrown when an algorithm isn’t implemented.

`JwtTokenInvalid`

Thrown when a JWT is invalid.

`JwtTokenNotBefore`

Thrown when a JWT is used before its nbf claim.

`JwtTokenExpired`

Thrown when a JWT has expired.

`JwtTokenIssuedAt`

Thrown when a JWT iat claim is in the future.

`JwtHeaderInvalid`

Thrown when a JWT header is invalid.

`JwtTokenSignatureMismatched`

Thrown when a JWT signature doesn’t match.