JSON Web Tokens

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

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

• Functions
• MCP Servers
• Caches

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 refreshes tokens automatically before expiration
• Functions can use the current cached token during calls through cache ID substitution

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. Add a Function parameter for the token, such as auth_token.
5. In the Function instructions, tell Leilani to provide the token cache ID as that parameter.
6. Reference the collected token field in the Function headers or request body.

Common example:

• Cache: Acme Service JWT
• Cache ID: 11111111-2222-3333-4444-555555555555
• Function field in Parameters: auth_token
• Header value: Bearer {/auth_token}

During the call, the Function can use the current cached token in headers or request bodies.

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.
• Do not select the JWT cache as the Function's output cache.

Limitations and notes

• The current UI supports creating and listing JSON Web Tokens.
• The current UI accepts claim values as strings.
• New calls use the latest available JWT cache value. If you change token configuration during an active call, retest on the next call.