langbot-app--langbot/docs/API_KEY_AUTH.md

API Key Authentication

LangBot now supports API key authentication for external systems to access its HTTP service API.

Managing API Keys

API keys can be managed through the web interface:

1. Log in to the LangBot web interface
2. Click the "API Keys" button at the bottom of the sidebar
3. Create, view, copy, or delete API keys as needed

Global API Key (config.yaml)

In addition to web-UI-created keys (stored in the database, prefixed lbk_), LangBot supports a global API key defined directly in data/config.yaml. This is useful for automated deployments, infrastructure-as-code, and AI agents that need API/MCP access without a login session and without creating a database record first.

api:
    port: 5300
    # ...
    global_api_key: 'your-strong-secret-here'   # leave empty to disable

Behavior:

• When api.global_api_key is a non-empty string, that exact value is accepted anywhere a normal API key is accepted — the X-API-Key header or Authorization: Bearer <key> — across the HTTP service API and the MCP server.
• The global key does not require the lbk_ prefix; use any sufficiently strong secret.
• Leave it empty ('', the default) to disable it entirely; only database-backed lbk_ keys will then be accepted.
• Existing installs are unaffected until you add the key — config completion only backfills top-level keys, and the lookup is defensive when the field is absent.

Security: the global key is stored in plaintext in config.yaml. Only enable it on trusted/internal deployments, keep the file permissions tight, always serve over HTTPS, and rotate the value if it may have leaked.

Using API Keys

Authentication Headers

Include your API key in the request header using one of these methods:

Method 1: X-API-Key header (Recommended)

X-API-Key: lbk_your_api_key_here

Method 2: Authorization Bearer token

Authorization: Bearer lbk_your_api_key_here

Available APIs

All existing LangBot APIs now support both user token and API key authentication. This means you can use API keys to access:

• Model Management - /api/v1/provider/models/llm and /api/v1/provider/models/embedding
• Bot Management - /api/v1/platform/bots
• Pipeline Management - /api/v1/pipelines
• Knowledge Base - /api/v1/knowledge/*
• MCP Servers - /api/v1/mcp/servers
• And more...

Authentication Methods

Each endpoint accepts either:

1. User Token (via Authorization: Bearer <user_jwt_token>) - for web UI and authenticated users
2. API Key (via X-API-Key or Authorization: Bearer <api_key>) - for external services

Example: Model Management

List All LLM Models

GET /api/v1/provider/models/llm
X-API-Key: lbk_your_api_key_here

Response:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "models": [
      {
        "uuid": "model-uuid",
        "name": "GPT-4",
        "description": "OpenAI GPT-4 model",
        "requester": "openai-chat-completions",
        "requester_config": {...},
        "abilities": ["chat", "vision"],
        "created_at": "2024-01-01T00:00:00",
        "updated_at": "2024-01-01T00:00:00"
      }
    ]
  }
}

Create a New LLM Model

POST /api/v1/provider/models/llm
X-API-Key: lbk_your_api_key_here
Content-Type: application/json

{
  "name": "My Custom Model",
  "description": "Description of the model",
  "requester": "openai-chat-completions",
  "requester_config": {
    "model": "gpt-4",
    "args": {}
  },
  "api_keys": [
    {
      "name": "default",
      "keys": ["sk-..."]
    }
  ],
  "abilities": ["chat"],
  "extra_args": {}
}

Update an LLM Model

PUT /api/v1/provider/models/llm/{model_uuid}
X-API-Key: lbk_your_api_key_here
Content-Type: application/json

{
  "name": "Updated Model Name",
  "description": "Updated description",
  ...
}

Delete an LLM Model

DELETE /api/v1/provider/models/llm/{model_uuid}
X-API-Key: lbk_your_api_key_here

Example: Bot Management

List All Bots

GET /api/v1/platform/bots
X-API-Key: lbk_your_api_key_here

Create a New Bot

POST /api/v1/platform/bots
X-API-Key: lbk_your_api_key_here
Content-Type: application/json

{
  "name": "My Bot",
  "adapter": "telegram",
  "config": {...}
}

Example: Pipeline Management

List All Pipelines

GET /api/v1/pipelines
X-API-Key: lbk_your_api_key_here

Create a New Pipeline

POST /api/v1/pipelines
X-API-Key: lbk_your_api_key_here
Content-Type: application/json

{
  "name": "My Pipeline",
  "config": {...}
}

Error Responses

401 Unauthorized

{
  "code": -1,
  "msg": "No valid authentication provided (user token or API key required)"
}

or

{
  "code": -1,
  "msg": "Invalid API key"
}

404 Not Found

{
  "code": -1,
  "msg": "Resource not found"
}

500 Internal Server Error

{
  "code": -2,
  "msg": "Error message details"
}

Security Best Practices

1. Keep API keys secure: Store them securely and never commit them to version control
2. Use HTTPS: Always use HTTPS in production to encrypt API key transmission
3. Rotate keys regularly: Create new API keys periodically and delete old ones
4. Use descriptive names: Give your API keys meaningful names to track their usage
5. Delete unused keys: Remove API keys that are no longer needed
6. Use X-API-Key header: Prefer using the X-API-Key header for clarity

Example: Python Client

import requests

API_KEY = "lbk_your_api_key_here"
BASE_URL = "http://your-langbot-server:5300"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# List all models
response = requests.get(f"{BASE_URL}/api/v1/provider/models/llm", headers=headers)
models = response.json()["data"]["models"]

print(f"Found {len(models)} models")
for model in models:
    print(f"- {model['name']}: {model['description']}")

# Create a new bot
bot_data = {
    "name": "My Telegram Bot",
    "adapter": "telegram",
    "config": {
        "token": "your-telegram-token"
    }
}

response = requests.post(
    f"{BASE_URL}/api/v1/platform/bots",
    headers=headers,
    json=bot_data
)

if response.status_code == 200:
    bot_uuid = response.json()["data"]["uuid"]
    print(f"Bot created with UUID: {bot_uuid}")

Example: cURL

# List all models
curl -X GET \
  -H "X-API-Key: lbk_your_api_key_here" \
  http://your-langbot-server:5300/api/v1/provider/models/llm

# Create a new pipeline
curl -X POST \
  -H "X-API-Key: lbk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Pipeline",
    "config": {...}
  }' \
  http://your-langbot-server:5300/api/v1/pipelines

# Get bot logs
curl -X POST \
  -H "X-API-Key: lbk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from_index": -1,
    "max_count": 10
  }' \
  http://your-langbot-server:5300/api/v1/platform/bots/{bot_uuid}/logs

Notes

• The same endpoints work for both the web UI (with user tokens) and external services (with API keys)
• No need to learn different API paths - use the existing API documentation with API key authentication
• All endpoints that previously required user authentication now also accept API keys