langflow/docs/docs/Develop/jwt-authentication.mdx

---
title: JWT authentication
slug: /jwt-authentication
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

Langflow supports symmetric or asymmetric JSON Web Tokens (JWT) for user authentication and authorization.

JWT is an [open standard](https://tools.ietf.org/html/rfc7519) for securely transmitting information between parties as a JSON object.
Use JWT to create credentials that automatically expire, enable stateless authentication without database storage, and work across distributed systems.

JWT authentication with the HS256 algorithm is enabled by default, but can be configured further with the `LANGFLOW_ALGORITHM` environment variable.

<details closed>
<summary>About the JWT structure and contents</summary>

When a user logs in with their username and password at the `/api/v1/login` endpoint, Langflow validates the credentials and creates a JWT token containing the user's identity and expiration time. This token is then used for subsequent API requests instead of sending credentials with each request.

A JWT consists of three parts separated by dots (`.`):

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```

* The header contains the token type and signing algorithm.
* The payload contains _claims_, which are token data for user information and expiration time.
* The signature is a secret key that ensures the token hasn't been tampered with.

Each part of the JWT is Base64URL-encoded.
You can paste this example JWT to decode the actual JSON data at [jwt.io](https://jwt.io/).

</details>

## Configure JWT environment variables

Configure JWT authentication in Langflow using the following environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `LANGFLOW_ALGORITHM` | JWT signing algorithm (`HS256`, `RS256`, or `RS512`) | `HS256` |
| `LANGFLOW_SECRET_KEY` | Secret key for HS256 signing | Auto-generated |
| `LANGFLOW_PRIVATE_KEY` | RSA private key for RS256/RS512 signing | Auto-generated |
| `LANGFLOW_PUBLIC_KEY` | RSA public key for RS256/RS512 verification | Derived from private key |
| `LANGFLOW_ACCESS_TOKEN_EXPIRE_SECONDS` | Access token expiration time | `3600` (1 hour) |
| `LANGFLOW_REFRESH_TOKEN_EXPIRE_SECONDS` | Refresh token expiration time | `604800` (7 days) |

## Configure signing algorithms

Langflow supports multiple signing algorithms and both symmetric (HS256) and asymmetric (RS256, RS512) JWTs.

Which method you choose depends upon your deployment's requirements.

### HS256 (Default)

HS256 is the default JWT algorithm, with a good security level for single-server deployments.
Langflow automatically generates and persists a secret key.
No configuration is necessary, but if you want to explicitly set it in the Langflow `.env`, the default value is `LANGFLOW_ALGORITHM=HS256`.

To generate a custom secure key instead of using the Langflow-generated secret key, do the following:

1. Generate a secure secret key with the Python secrets module or OpenSSL.
    The key must be at least 32 characters long.

    **Using Python:**

    ```bash
    python -c "import secrets; print(secrets.token_urlsafe(32))"
    ```

    **Using OpenSSL:**

    ```bash
    openssl rand -base64 32
    ```

2. Set the value for `LANGFLOW_SECRET_KEY` in your `.env` file.
    ```bash
    LANGFLOW_ALGORITHM="HS256"
    LANGFLOW_SECRET_KEY="your-custom-secret-key"
    ```

### RS256

The RS256 signing algorithm provides better security for production deployments by using a pair of private and public keys.
The private key signs tokens, and the public verifies them.
The private key must be kept secret, while the public key can be safely shared.

To automatically generate a private and public key pair and store it in the Langflow [`LANGFLOW_CONFIG_DIR`](/logging), set `LANGFLOW_ALGORITHM="RS256"` in your Langflow `.env`.
When Langflow starts, it will:
1. Check if RSA keys exist in the configuration directory.
2. If not, generate a new 2048-bit RSA key pair.
3. Save the keys to `private_key.pem` and `public_key.pem`.
4. Reuse the same keys on subsequent startups.

To use a custom private key instead of the auto-generated keys, set the following in your `.env` file.
The `LANGFLOW_PUBLIC_KEY` will be automatically derived from the private key.

```bash
LANGFLOW_ALGORITHM=RS256
LANGFLOW_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEF...
-----END PRIVATE KEY-----"
```

To use a custom key pair, set both keys in your Langflow `.env` file.

```bash
LANGFLOW_ALGORITHM=RS256
LANGFLOW_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEF...
-----END PRIVATE KEY-----"
LANGFLOW_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOC...
-----END PUBLIC KEY-----"
```

To generate an RSA key pair manually, do the following:

1. Generate a 2048-bit private key:
   ```bash
   openssl genrsa -out private_key.pem 2048
   ```

2. Extract the public key from the private key:
   ```bash
   openssl rsa -in private_key.pem -pubout -out public_key.pem
   ```

3. Verify the keys were created:
   ```bash
   cat private_key.pem
   cat public_key.pem
   ```

### RS512

RS512 uses the same RSA format of private and public keys as RS256, but uses the SHA-512 hashing algorithm for greater security.
The private key signs tokens, and the public verifies them.
The private key must be kept secret, while the public key can be safely shared.

To automatically generate a private and public key pair and store it in the Langflow [`LANGFLOW_CONFIG_DIR`](/logging), set `LANGFLOW_ALGORITHM="RS512"` in your Langflow `.env`.
When Langflow starts, it does the following:
1. Check if RSA keys exist in the configuration directory.
2. If not, generate a new 2048-bit RSA key pair.
3. Save the keys to `private_key.pem` and `public_key.pem`.
4. Reuse the same keys on subsequent startups.

To use a custom private key instead of the auto-generated keys, set the following in your `.env` file.
The `LANGFLOW_PUBLIC_KEY` will be automatically derived from the private key.

```bash
LANGFLOW_ALGORITHM=RS512
LANGFLOW_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEF...
-----END PRIVATE KEY-----"
```

To use a custom key pair, set both keys in your Langflow `.env` file.

```bash
LANGFLOW_ALGORITHM=RS512
LANGFLOW_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEF...
-----END PRIVATE KEY-----"
LANGFLOW_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOC...
-----END PUBLIC KEY-----"
```

To generate an RSA key pair manually, do the following:

1. Generate a 2048-bit private key:
   ```bash
   openssl genrsa -out private_key.pem 2048
   ```

2. Extract the public key from the private key:
   ```bash
   openssl rsa -in private_key.pem -pubout -out public_key.pem
   ```

3. Verify the keys were created:
   ```bash
   cat private_key.pem
   cat public_key.pem
   ```

## Configure Docker and Kubernetes deployments

Use Docker with HS256 (symmetric) for single-server deployments or development environments where simplicity is preferred.

Use Docker or Kubernetes with RS256 (asymmetric) for production deployments requiring enhanced security with private/public key pairs.

### Docker with HS256

1. Add the value for your JWT secret key to the Langflow `.env` file.
    ```bash
    JWT_SECRET_KEY=your-secret-key
    ```

2. Set the signing algorithm and include a variable for the secret key in the Docker Compose file.
    ```yaml
    version: "3.8"
    services:
      langflow:
        image: langflowai/langflow:latest
        environment:
          - LANGFLOW_ALGORITHM=HS256
          - LANGFLOW_SECRET_KEY=${JWT_SECRET_KEY}  # Set in .env file
        volumes:
          - langflow_data:/app/langflow

    volumes:
      langflow_data:
    ```

### Docker with RS256

To use Langflow's automatically generated key pair, set the `RS256` signing algorithm in the Docker Compose file.

```yaml
# docker-compose.yml
version: "3.8"
services:
  langflow:
    image: langflowai/langflow:latest
    environment:
      - LANGFLOW_ALGORITHM=RS256
    volumes:
      - langflow_data:/app/langflow  # Keys stored here

volumes:
  langflow_data:
```

To mount an existing key pair, set the `RS256` signing algorithm and mount the private and public keys as volumes.

```yaml
# docker-compose.yml
version: "3.8"
services:
  langflow:
    image: langflowai/langflow:latest
    environment:
      - LANGFLOW_ALGORITHM=RS256
    volumes:
      - ./keys/private_key.pem:/app/langflow/private_key.pem:ro
      - ./keys/public_key.pem:/app/langflow/public_key.pem:ro
      - langflow_data:/app/langflow

volumes:
  langflow_data:
```

### Kubernetes with RS256

Store JWT keys as Kubernetes Secrets and reference them in your Langflow deployment configuration.

```yaml
# jwt-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: langflow-jwt-keys
type: Opaque
stringData:
  algorithm: "RS256"
  private-key: |
    -----BEGIN PRIVATE KEY-----
    MIIEvgIBADANBgkqhkiG9w0BAQEF...
    -----END PRIVATE KEY-----
  public-key: |
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOC...
    -----END PUBLIC KEY-----
---
# langflow-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: langflow
spec:
  template:
    spec:
      containers:
        - name: langflow
          image: langflowai/langflow:latest
          env:
            - name: LANGFLOW_ALGORITHM
              valueFrom:
                secretKeyRef:
                  name: langflow-jwt-keys
                  key: algorithm
            - name: LANGFLOW_PRIVATE_KEY
              valueFrom:
                secretKeyRef:
                  name: langflow-jwt-keys
                  key: private-key
            - name: LANGFLOW_PUBLIC_KEY
              valueFrom:
                secretKeyRef:
                  name: langflow-jwt-keys
                  key: public-key
```

## Configure token expiration

To configure access and refresh token expiration times, set the values in the Langflow `.env`.

```bash
LANGFLOW_ACCESS_TOKEN_EXPIRE_SECONDS=3600  # 1 hour
LANGFLOW_REFRESH_TOKEN_EXPIRE_SECONDS=604800  # 7 days
```

Access tokens authenticate API requests and typically expire within 15 minutes to 1 hour to limit security risks.

Refresh tokens obtain new access tokens without requiring the user to log in again.
Refresh tokens typically expire within 7 to 30 days.

When an access token expires, the client can use the refresh token to get a new access token from the `/api/v1/refresh` endpoint.
This maintains the user's session without prompting for credentials again.

## See also

- [Langflow API keys and authentication](/api-keys-and-authentication)
- [JWT.io](https://jwt.io/)
- [RFC 7519 specification](https://tools.ietf.org/html/rfc7519)
- [OWASP JWT Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html)
- [Langflow Security Best Practices](/security)