# Builder

(builder)

## Overview

The `JWT Builder` facilitates the creation of JSON Web Tokens by providing methods for setting headers, adding payload claims, and signing the token with a specified algorithm. Its chaining capabilities enable streamlined construction of tokens for secure communication.

## Functionality

Headers can be added using the `header(key, value)` method, specifying header names and values. Payloads, including claims, can be defined with `payload(payload)` or extended using `withClaim(key, value)`. For specifying token expiration, the `withExpires(expire)` method adds an "exp" claim. The `sign(alg)` method finalizes the token by signing it with the chosen algorithm, automatically including the algorithm ("alg") in the header.

## Methods Summarized

| Type                                                                                     | Name                                          | Summary                                                 |
| ---------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------- |
| [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) | [header(key, value)](#header-key-value)       | Adds a header to the JWT token.                         |
| [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) | [payload(payload)](#payload-payload)          | Adds the payload (claims) to the web token.             |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string)             | [sign(alg)](#sign-alg)                        | Sign the token with the given algorithm.                |
| [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) | [withClaim(key, value)](#withclaim-key-value) | Adds data to the payload, which contains the claims.    |
| [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) | [withExpires(expire)](#withexpires-expire)    | Add a specific Expires At ("exp") claim to the Payload. |

## Methods Detailed

### header(key, value)

Adds a header to the JWT token.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** a string representing the header name
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** can be a string

**Returns:** [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) the jwt builder for method chaining

### payload(payload)

Adds the payload (claims) to the web token.

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **payload** a json containing the data,\
          e.g. {'some': 'data', 'somemore': 'data2'}

**Returns:** [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) the jwt builder for method chaining

### sign(alg)

Sign the token with the given algorithm.\
The 'alg' claim is automatically added to the token header.

**Parameters**

* [Algorithm](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/algorithm) **alg** the algorithm used to sign the token.

**Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a string representing the constructed JSON Web Token.

### withClaim(key, value)

Adds data to the payload, which contains the claims.\
Claims are statements about an entity (typically, the user) and additional data.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** a string representing the claim name (e.g. 'iss' which stands for issuer; 'email', 'name', etc.)
* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **value** can be a string, a boolean, a date, a number or an array

**Returns:** [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) the jwt builder for method chaining

### withExpires(expire)

Add a specific Expires At ("exp") claim to the Payload.

**Parameters**

* [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **expire** a date representing the expiration time of the token

**Returns:** [Builder](https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder) the jwt builder for method chaining

***