# 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](/reference/servoyextensions/server-plugins/jwt/builder.md) | [header(key, value)](#header-key-value)       | Adds a header to the JWT token.                         |
| [Builder](/reference/servoyextensions/server-plugins/jwt/builder.md) | [payload(payload)](#payload-payload)          | Adds the payload (claims) to the web token.             |
| [String](/reference/servoycore/dev-api/js-lib/string.md)             | [sign(alg)](#sign-alg)                        | Sign the token with the given algorithm.                |
| [Builder](/reference/servoyextensions/server-plugins/jwt/builder.md) | [withClaim(key, value)](#withclaim-key-value) | Adds data to the payload, which contains the claims.    |
| [Builder](/reference/servoyextensions/server-plugins/jwt/builder.md) | [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](/reference/servoycore/dev-api/js-lib/string.md) **key** a string representing the header name
* [String](/reference/servoycore/dev-api/js-lib/string.md) **value** can be a string

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

### payload(payload)

Adds the payload (claims) to the web token.

**Parameters**

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

**Returns:** [Builder](/reference/servoyextensions/server-plugins/jwt/builder.md) 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](/reference/servoyextensions/server-plugins/jwt/algorithm.md) **alg** the algorithm used to sign the token.

**Returns:** [String](/reference/servoycore/dev-api/js-lib/string.md) 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](/reference/servoycore/dev-api/js-lib/string.md) **key** a string representing the claim name (e.g. 'iss' which stands for issuer; 'email', 'name', etc.)
* [Object](/reference/servoycore/dev-api/js-lib/object.md) **value** can be a string, a boolean, a date, a number or an array

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

### withExpires(expire)

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

**Parameters**

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

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

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.servoy.com/reference/servoyextensions/server-plugins/jwt/builder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.