Authentication Configuration

Configure API key-based authentication for your Lit Status server with two permission levels: read-only and full access.

API Key Types

Read-Only Keys

Can perform GET requests (view data)
Cannot create, update, or delete functions
Cannot log executions
Ideal for dashboards and monitoring tools

Full Access Keys

Can perform all operations
Create/update functions
Log executions
View all data
Required for SDK write operations

Generating API Keys

Use the built-in scripts to generate secure API keys:

Generate Read-Only Key

bun run gen:read-key

Output:

🔑 Generated read-only API key: lit_readonly_abc123def456...

Add this to your .env file:
READ_ONLY_API_KEYS='["lit_readonly_abc123def456..."]'

Generate Full Access Key

bun run gen:write-key

Output:

🔑 Generated full access API key: lit_write_xyz789uvw123...

Add this to your .env file:
FULL_ACCESS_API_KEYS='["lit_write_xyz789uvw123..."]'

Environment Configuration

Add the generated keys to your .env file:

# Read-only API keys (JSON array)
READ_ONLY_API_KEYS='["lit_readonly_key1", "lit_readonly_key2"]'

# Full access API keys (JSON array)
FULL_ACCESS_API_KEYS='["lit_write_key1", "lit_write_key2"]'

# Database connection
DATABASE_URL="postgresql://username:password@localhost:5432/litstatus"

Using API Keys

HTTP Headers

Include the API key in the X-API-Key header:

curl -H "X-API-Key: your-api-key-here" \
     http://localhost:3000/health

SDK Configuration

import { createLitStatusClient } from '@lit-protocol/lit-status-sdk';

const client = createLitStatusClient({
  url: 'http://localhost:3000',
  apiKey: 'your-api-key-here'
});

Permission Matrix

Operation	Read-Only	Full Access
Health Check	✅	✅
Get Functions	✅	✅
Get Function Metrics	✅	✅
Get Time-Series Data	✅	✅
Export Metrics	✅	✅
Get Filter Options	✅	✅
Create/Update Function	❌	✅
Log Execution	❌	✅

Error Responses

Missing API Key

{
  "error": "API key required",
  "details": "Please provide an API key in the 'x-api-key' header"
}

Invalid API Key

{
  "error": "Invalid API key",
  "details": "The provided API key is not valid"
}

Insufficient Permissions

{
  "error": "Insufficient permissions", 
  "details": "Read-only API key cannot perform write operations. Use a full access key for this endpoint."
}

Security Best Practices

Key Management

Store API keys in environment variables, never in code
Use different keys for different environments (dev/staging/prod)
Rotate keys regularly
Use read-only keys wherever possible

Environment Separation

# Development
READ_ONLY_API_KEYS='["dev_readonly_key"]'
FULL_ACCESS_API_KEYS='["dev_write_key"]'

# Production  
READ_ONLY_API_KEYS='["prod_readonly_key1", "prod_readonly_key2"]'
FULL_ACCESS_API_KEYS='["prod_write_key"]'

Key Rotation

Generate new keys
Update environment variables
Deploy the configuration
Update client applications
Remove old keys after transition

Monitoring

Check authentication status via health endpoint:

curl -H "X-API-Key: your-key" http://localhost:3000/health

Response:

{
  "status": "ok",
  "connected": true,
  "authentication": {
    "enabled": true,
    "readOnlyKeysConfigured": 2,
    "fullAccessKeysConfigured": 1
  }
}

Advanced Configuration

Custom Header Name

Modify the header name in src/services/auth/apiKeyAuth.ts:

const API_KEY_HEADER = 'authorization'; // Custom header name

Multiple Key Sources

Support multiple environment variables:

const readOnlyKeys = [
  ...parseApiKeys('READ_ONLY_API_KEYS'),
  ...parseApiKeys('DASHBOARD_API_KEYS'),
  ...parseApiKeys('MONITORING_API_KEYS')
];

Key Validation

Add custom validation logic:

function validateApiKey(apiKey: string): boolean {
  // Custom validation logic
  if (!apiKey.startsWith('lit_')) return false;
  if (apiKey.length < 32) return false;
  return keys.includes(apiKey);
}

Authentication

On this page