# JSON Web Tokens

Open your agent in the console and select **Functions**, then open the **JSON Web Tokens** tab.

This page documents the JSON Web Tokens tab. Related pages:

- [Functions](3-functions.md)
- [Caches](3.2-caches.md)

## What a JSON Web Token does

A JSON Web Token configuration signs a JWT and stores the token in a selected cache.

Use this when a Function needs a bearer token or signed credential that should refresh automatically.

The token lifetime follows the selected cache's TTL.

## Before you create one

Create the cache first in the **Caches** tab.

Use a dedicated cache for each token. Do not reuse the same cache for both:

- a JWT
- a Function result

## JSON Web Tokens tab

The tab shows a table with these columns:

- `Name`
- `Cache`
- `Algorithm`
- `Key Type`
- `Cache TTL`

The current UI supports creating and listing JSON Web Tokens from this tab.

## Create a JSON Web Token

Select **Create** to open the JSON Web Token modal.

### Name

Use a short, descriptive name.

Examples:

- `acme_api_jwt`
- `crm_service_jwt`

### Cache

Select the cache where the signed token should be stored.

The cache TTL controls how long the token is valid before it is refreshed.

### Algorithm

Supported algorithms:

- `HS256`
- `HS384`
- `HS512`
- `ES256`
- `ES384`
- `RS256`
- `RS384`
- `RS512`
- `PS256`
- `PS384`
- `PS512`
- `EdDSA`

Choose the algorithm required by the target service.

### Encoding Key Type

Supported key types:

- `EcDer`
- `EdDer`
- `RsaDer`
- `Secret`
- `Base64Secret`
- `EcPem`
- `EdPem`
- `RsaPem`
- `UrlSafeBase64Secret`

Use the key type that matches the key material provided by the external system.

### Encoding Key

Enter the signing key in the format required by the selected key type.

Guidance:

- for DER key types, enter base64-encoded DER bytes
- for PEM and secret-based key types, enter the key as plain text

### Claims

Use the **Claims** table to add base claims as name and value pairs.

Examples:

- `iss`
- `aud`
- `sub`
- `scope`

Important behavior:

- the current UI accepts claim values as strings
- Leilani adds `iat` and `exp` automatically

## Refresh behavior

Leilani refreshes tokens automatically.

Operationally, this means:

- you select the cache and its TTL
- Leilani keeps the cache populated with a current signed token
- Functions can use that cached token during calls

## Using a JWT with a Function

Recommended pattern:

1. Create a dedicated cache for the token.
2. Create the JSON Web Token and point it at that cache.
3. Create a Function that needs the token.
4. In the Function instructions, make it clear which cached token should be used.
5. Reference the collected token field in the Function headers or request body.

Common example:

- Cache: `Acme Service JWT`
- Function field in Parameters: `auth_token`
- Header value: `Bearer {/auth_token}`

If the Function response should also be cached, use a second cache for the Function result.

## Operator guidance

- Use clear names for both the JWT and its cache.
- Match the cache TTL to the token lifetime expected by the target service.
- Keep claims minimal and service-specific.
- Store one token per cache.

## Limitations and notes

- The current UI supports creating and listing JSON Web Tokens.
- The current UI accepts claim values as strings.