# Azion `JWT` library

import DocButton from '~/components/webkit/DocButton.vue';

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.

<DocButton href="/en/documentation/products/azion-lib/overview/" label="Go to Azion Libraries Overview" kind="secondary" size="medium" />

---

## Usage

### `sign`

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

Example:

```typescript
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:

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.