API Key Management Guide - MCP Server with LangGraph

API keys provide simple, long-lived authentication for CLI tools, webhooks, and legacy integrations. All API keys are exchanged for JWTs and stored securely in Keycloak. See ADR-0034 for architectural details.

Overview

API keys are:

Stored in Keycloak (user attributes with bcrypt hashing)
Exchanged for JWTs (standardized authentication)
User-attributed (linked to user or service principal identity)
Rotatable (without changing client code)
Expirable (default 365 days)
Rate-limited (5 keys per user)

Creating API Keys

Via API

curl -X POST https://api.example.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "expires_days": 365
  }'

Response:

{
  "key_id": "abc123",
  "api_key": "mcpkey_live_EXAMPLE1234567890abcdefghijklmnop...",
  "name": "Production API Key",
  "created": "2025-01-28T00:00:00Z",
  "expires_at": "2026-01-28T00:00:00Z",
  "message": "Save this API key securely. It will not be shown again."
}

⚠️ Save the api_key value immediately - it cannot be retrieved later.

Via CLI

python scripts/create_api_key.py --name "My API Key" --expires 90

Using API Keys

Direct API Calls

curl -X POST https://api.example.com/message \
  -H "apikey: mcpkey_live_EXAMPLE1234567890abcdefghijklmnop..." \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello, world!"}'

Python Client

import httpx

API_KEY = "mcpkey_live_EXAMPLE1234567890abcdefghijklmnop..."

async def make_request(query: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/message",
            headers={"apikey": API_KEY},
            json={"query": query}
        )
        return response.json()

JavaScript Client

const API_KEY = 'mcpkey_live_EXAMPLE1234567890abcdefghijklmnop...';

async function makeRequest(query) {
  const response = await fetch('https://api.example.com/message', {
    method: 'POST',
    headers: {
      'apikey': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query }),
  });
  return response.json();
}

How API Keys Work

Exchange Flow

Client sends request with API key header
Kong custom plugin intercepts request
Plugin validates key with Keycloak (via MCP server)
Keycloak returns JWT if key is valid
Plugin replaces API key with JWT in Authorization header
Request forwarded to MCP server with JWT
MCP server validates JWT (standard flow)

Storage Format

API keys are stored in Keycloak user attributes as bcrypt hashes:

{
  "username": "alice",
  "attributes": {
    "apiKeys": [
      "key:abc123:$2b$12$abcd1234...",
      "key:xyz789:$2b$12$wxyz5678..."
    ],
    "apiKey_abc123_name": "Production Key",
    "apiKey_abc123_created": "2025-01-28T00:00:00Z",
    "apiKey_abc123_lastUsed": "2025-01-28T12:30:00Z",
    "apiKey_abc123_expiresAt": "2026-01-28T00:00:00Z"
  }
}

Managing API Keys

List Keys

curl -X GET https://api.example.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT"

Response:

[
  {
    "key_id": "abc123",
    "name": "Production Key",
    "created": "2025-01-28T00:00:00Z",
    "last_used": "2025-01-28T12:30:00Z",
    "expires_at": "2026-01-28T00:00:00Z"
  },
  {
    "key_id": "xyz789",
    "name": "Test Key",
    "created": "2025-01-15T00:00:00Z",
    "expires_at": "2025-04-15T00:00:00Z"
  }
]

Rotate Key

curl -X POST https://api.example.com/api/v1/api-keys/abc123/rotate \
  -H "Authorization: Bearer YOUR_JWT"

Response:

{
  "key_id": "abc123",
  "new_api_key": "sk_live_NEW_KEY_HERE...",
  "message": "API key rotated successfully. Update your configuration."
}

Revoke Key

curl -X DELETE https://api.example.com/api/v1/api-keys/abc123 \
  -H "Authorization: Bearer YOUR_JWT"

Security Best Practices

Storage

✅ DO: Store in secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager)
✅ DO: Use environment variables in production
❌ DON’T: Commit to version control
❌ DON’T: Log API keys
❌ DON’T: Include in error messages

Rotation

✅ DO: Rotate keys every 90-180 days
✅ DO: Rotate immediately if compromised
✅ DO: Test new key before revoking old key
❌ DON’T: Share keys across multiple systems
❌ DON’T: Reuse revoked keys

Usage

✅ DO: Use HTTPS only
✅ DO: Monitor key usage (last_used timestamp)
✅ DO: Set appropriate expiration dates
✅ DO: Use different keys for dev/staging/production
❌ DON’T: Use in client-side code (browsers)
❌ DON’T: Share keys in public repositories

Rate Limiting

API keys are subject to rate limits based on user tier:

Tier	Rate Limit
Free	60 req/min, 1,000 req/hour
Premium	300 req/min, 10,000 req/hour
Enterprise	1,000 req/min, 100,000 req/hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1706480400

Monitoring

Key Usage

Check last_used timestamps to identify unused keys:

curl -X GET /api/v1/api-keys | jq '.[] | select(.last_used == null)'

Prometheus Metrics

## API key validation rate
rate(api_key_validations_total[5m])

## API key validation errors
rate(api_key_validations_errors_total[5m])

## Cache hit rate
api_key_cache_hits / (api_key_cache_hits + api_key_cache_misses)

Troubleshooting

Invalid API Key

Symptom: 401 Unauthorized - Invalid or expired API key Solutions:

Verify key is copied correctly (no whitespace)
Check expiration date: GET /api/v1/api-keys
Ensure user account is enabled
Verify key hasn’t been revoked

Kong Validation Timeout

Symptom: 504 Gateway Timeout Solutions:

Check MCP server health
Verify Kong→MCP connectivity
Increase timeout in Kong plugin config
Check Keycloak availability

Cache Issues

Symptom: Old key still works after revocation Solutions:

Wait for cache TTL (5 minutes by default)
Clear Kong cache: kong cache:purge apikey:*
Reduce cache TTL if faster revocation needed

Migration from Kong-Stored Keys

Step 1: Export Existing Keys

## List Kong consumers
curl http://kong-admin:8001/consumers

## Export key-auth credentials
curl http://kong-admin:8001/consumers/USER/key-auth

Step 2: Recreate in Keycloak

## For each user, create new API key
curl -X POST /api/v1/api-keys \
  -H "Authorization: Bearer USER_JWT" \
  -d '{"name": "Migrated Key"}'

Step 3: Update Clients

Provide new API keys to clients (gradual rollout).

Step 4: Sunset Old Keys

After migration period, remove Kong key-auth plugin.

Examples

CLI Tool Authentication

#!/usr/bin/env python3
import os
import httpx

API_KEY = os.getenv("MCP_API_KEY")

async def main():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/message",
            headers={"apikey": API_KEY},
            json={"query": "Process data"}
        )
        print(response.json())

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Webhook Integration

## External system calls your webhook with API key
from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.post("/webhook")
async def handle_webhook(
    data: dict,
    apikey: str = Header(None)
):
    # Webhook calls MCP with your API key
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/message",
            headers={"apikey": apikey},
            json={"query": data["message"]}
        )
        return response.json()

References

Architecture & API Docs

ADR: ADR-0034: API Key to JWT Exchange
API Reference: API Keys API
Kong Plugin: kong-apikey-jwt-exchange
Security: See “Security Best Practices” section above

Service Principals - Machine-to-machine authentication for batch jobs and CI/CD
SCIM Provisioning - Automated provisioning of API keys for users
Identity Federation - External IdP integration
Authentication Migration - Migrating to v2.8.0 authentication

Quick Start

LLM Providers

Production

Migration

Authorization

Enterprise Identity & Access

Secrets Management

Sessions & Storage

Observability

​Overview

​Creating API Keys

​Via API

​Via CLI

​Using API Keys

​Direct API Calls

​Python Client

​JavaScript Client

​How API Keys Work

​Exchange Flow

​Storage Format

​Managing API Keys

​List Keys

​Rotate Key

​Revoke Key

​Security Best Practices

​Storage

​Rotation

​Usage

​Rate Limiting

​Monitoring

​Key Usage

​Prometheus Metrics

​Troubleshooting

​Invalid API Key

​Kong Validation Timeout

​Cache Issues

​Migration from Kong-Stored Keys

​Step 1: Export Existing Keys

​Step 2: Recreate in Keycloak

​Step 3: Update Clients

​Step 4: Sunset Old Keys

​Examples

​CLI Tool Authentication

​Webhook Integration

​References

​Architecture & API Docs

​Related Guides

Overview

Creating API Keys

Via API

Via CLI

Using API Keys

Direct API Calls

Python Client

JavaScript Client

How API Keys Work

Exchange Flow

Storage Format

Managing API Keys

List Keys

Rotate Key

Revoke Key

Security Best Practices

Storage

Rotation

Usage

Rate Limiting

Monitoring

Key Usage

Prometheus Metrics

Troubleshooting

Invalid API Key

Kong Validation Timeout

Cache Issues

Migration from Kong-Stored Keys

Step 1: Export Existing Keys

Step 2: Recreate in Keycloak

Step 3: Update Clients

Step 4: Sunset Old Keys

Examples

CLI Tool Authentication

Webhook Integration

References

Architecture & API Docs

Related Guides