API Authentication Guide

Overview

better-ccflare now supports optional API authentication that allows you to secure your proxy endpoint with API keys. When API keys are configured, all requests to the proxy API must include a valid API key.

🚀 Quick Start

1. Generate Your First API Key

# Generate a new API key
better-ccflare --generate-api-key "Production App"

# ✅ API Key Generated Successfully!
# Name: Production App
# Key: btr-abcdef1234567890...  ⚠️  Save this key now - it won't be shown again
# Prefix: 12345678
# Created: Tue Dec 10 2024 10:30:45 GMT

# Usage:
#   Include this key in your requests using the 'x-api-key' header:
#   x-api-key: btr-abcdef1234567890...

# Example:
# curl -X POST http://localhost:8080/v1/messages \
#   -H "Content-Type: application/json" \
#   -H "x-api-key: btr-abcdef1234567890..." \
#   -d '{"model": "claude-3-haiku-20240307", "messages": [{"role": "user", "content": "Hello"}]}'

2. Use the API Key

# Make API requests with your key
curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: btr-abcdef1234567890..." \
  -d '{
    "model": "claude-3-haiku-20240307",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

🔐 Authentication Features

Secure Key Generation

32+ character random keys with btr- prefix
One-way hashing using scrypt with unique salts
Usage tracking with last used timestamp and request count
One-time display - full key shown only during generation

Multiple Header Formats

# x-api-key header (Anthropic format)
x-api-key: btr-abcdef1234567890...

# Authorization: Bearer header (Standard format)
Authorization: Bearer btr-abcdef1234567890...

Flexible Management

CLI commands for key generation and management
Web dashboard with visual key management
REST API for programmatic access
Enable/disable keys without deletion
Usage statistics and monitoring

📋 CLI Commands

Generate API Keys

# Generate new API key
better-ccflare --generate-api-key "My App"

# Generate multiple keys for different environments
better-ccflare --generate-api-key "Production"
better-ccflare --generate-api-key "Development"
better-ccflare --generate-api-key "Testing"

List API Keys

# List all API keys with status
better-ccflare --list-api-keys

# Output:
# API Keys:
#   Production (12345678)
#     Status: Active
#     Created: December 10, 2024
#     Last Used: Never
#     Usage Count: 0
#
# Statistics:
#   Total: 1
#   Active: 1
#   Inactive: 0

Manage API Keys

# Disable an API key (temporary)
better-ccflare --disable-api-key "Production"

# Enable a disabled API key
better-ccflare --enable-api-key "Production"

# Delete an API key permanently
better-ccflare --delete-api-key "Production"

🌐 Web Dashboard

Access the API Keys Interface

Navigate to your better-ccflare dashboard (default: http://localhost:8080)
Click "API Keys" in the navigation menu
View statistics, generate new keys, and manage existing ones

Dashboard Features

Statistics cards showing total, active, and inactive keys
One-time key display with secure copy functionality
Real-time status updates with toggle controls
Usage tracking with last used timestamps
Delete confirmation with security warnings

🔌 REST API

API Key Management Endpoints

List All API Keys

curl -X GET http://localhost:8080/api/api-keys \
  -H "x-api-key: your-api-key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production App",
      "prefixLast8": "12345678",
      "createdAt": "2024-12-10T10:30:45.123Z",
      "lastUsed": "2024-12-10T11:15:22.456Z",
      "usageCount": 15,
      "isActive": true
    }
  ],
  "count": 1
}

Generate New API Key

curl -X POST http://localhost:8080/api/api-keys \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"name": "New Integration"}'

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "New Integration",
    "apiKey": "btr-abcdef1234567890...",
    "prefixLast8": "12345678",
    "createdAt": "2024-12-10T10:30:45.123Z"
  }
}

Get API Key Statistics

curl -X GET http://localhost:8080/api/api-keys/stats \
  -H "x-api-key: your-api-key"

Response:

{
  "success": true,
  "data": {
    "total": 3,
    "active": 2,
    "inactive": 1
  }
}

Enable/Disable API Keys

# Disable API key
curl -X POST http://localhost:8080/api/api-keys/Production/disable \
  -H "x-api-key: your-api-key"

# Enable API key
curl -X POST http://localhost:8080/api/api-keys/Production/enable \
  -H "x-api-key: your-api-key"

# Delete API key
curl -X DELETE http://localhost:8080/api/api-keys/Production \
  -H "x-api-key: your-api-key"

🔒 Security Features

Key Storage Security

Hashed Storage: API keys are stored using scrypt with unique salts
Prefix Only: Only the last 8 characters are stored in clear text
Secure Generation: Cryptographically secure random key generation
One-Time Display: Full API keys are shown only during generation

Authentication Flow

Check if authentication enabled (active API keys exist)
Validate request path (dashboard, health, OAuth endpoints are exempt)
Extract API key from request headers
Verify against hashed keys in database
Update usage statistics on successful authentication

Rate Limiting & Usage Tracking

Request counting per API key
Last used timestamp tracking
Usage statistics available in dashboard and CLI
Performance monitoring with minimal overhead

🛡️ Security Best Practices

API Key Management

Never share API keys in public code or repositories
Use descriptive names for easier management (e.g., "Production-Web-App")
Rotate keys regularly for high-security applications
Delete unused keys to minimize attack surface
Monitor usage to detect unauthorized access

Environment-Specific Keys

# Production environment
better-ccflare --generate-api-key "Production-Web-App"
better-ccflare --generate-api-key "Production-API"

# Development environment
better-ccflare --generate-api-key "Dev-Local"
better-ccflare --generate-api-key "Dev-Testing"

# Staging environment
better-ccflare --generate-api-key "Staging-App"

Access Control

# Create keys with limited scope
better-ccflare --generate-api-key "Read-Only-Integration"
better-ccflare --generate-api-key "Write-Access-Service"

⚡ Performance

Authentication Overhead

< 10ms average overhead per request
Minimal database impact with efficient queries
Optimized key validation with fast hash verification
Concurrent request support for high-throughput scenarios

Performance Benchmark

Run the performance benchmark script to test your setup:

# Run comprehensive performance tests
./test-performance-benchmark.sh

Expected Results:

< 10ms authentication overhead
> 1000 requests/second with authentication
< 1MB memory increase under sustained load

🔄 Migration Guide

From No Authentication to Authenticated

Current Setup: No authentication required

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-3-haiku-20240307", "messages": [...]}'

Generate First API Key:

better-ccflare --generate-api-key "First Key"

Update Client Code:

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: btr-abcdef1234567890..." \
  -d '{"model": "claude-3-haiku-20240307", "messages": [...]}'

Rollout Gradually: Deploy to different environments with different keys

🐛 Troubleshooting

Common Issues

API Key Not Working

# Check if API key exists and is active
better-ccflare --list-api-keys

# Verify key format (should start with "btr-")
echo "btr-abcdef1234567890..." | grep -E "^btr-[a-zA-Z0-9]{32}$"

Authentication Errors

# Test API key validity
curl -v -X GET http://localhost:8080/api/stats \
  -H "x-api-key: your-key-here"

# Check server logs for authentication details
tail -f ~/.config/better-ccflare/better-ccflare.log

Dashboard Issues

# Check if server is running
curl http://localhost:8080/health

# Restart server with clean state
pkill better-ccflare
better-ccflare --serve

Debug Mode

Enable verbose logging for authentication debugging:

# Start server with debug logging
DEBUG=auth:* better-ccflare --serve

📚 Reference

API Key Format

Format: btr- + 32 random alphanumeric characters
Example: btr-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890
Total Length: 36 characters
Valid Characters: A-Z, a-z, 0-9

Header Priority

x-api-key (preferred for Claude API compatibility)
Authorization: Bearer <key> (standard HTTP format)

Path Exemptions

The following paths are exempt from authentication:

/ (dashboard home)
/dashboard/* (web dashboard)
/health (health check)
/api/oauth/* (OAuth flow)
/api/api-keys/* (API key management)

CLI Reference

# Help
better-ccflare --help

# Version
better-ccflare --version

# API Key Commands
better-ccflare --generate-api-key <name>
better-ccflare --list-api-keys
better-ccflare --disable-api-key <name>
better-ccflare --enable-api-key <name>
better-ccflare --delete-api-key <name>

🚀 Advanced Usage

Programmatic Key Management

// Generate API key via REST API
const response = await fetch('http://localhost:8080/api/api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'admin-key'
  },
  body: JSON.stringify({
    name: 'Programmatic Key'
  })
});

const { apiKey, prefixLast8 } = await response.json();
console.log(`Generated key: ${apiKey} (prefix: ${prefixLast8})`);

Automation Scripts

#!/bin/bash
# deploy.sh - Deployment automation script

# Generate deployment keys
PROD_KEY=$(better-ccflare --generate-api-key "production" | grep "Key:" | awk '{print $2}')
STAGING_KEY=$(better-ccflare --generate-api-key "staging" | grep "Key:" | awk '{print $2}')

# Store keys securely (example with environment variables)
export PROD_API_KEY="$PROD_KEY"
export STAGING_API_KEY="$STAGING_KEY"

echo "✅ API keys generated for deployment"

Docker Integration

# Dockerfile.example
FROM node:18-alpine

# Install better-ccflare
RUN npm install -g better-ccflare

# Generate API key during build
RUN better-ccflare --generate-api-key "docker-container" | grep "Key:" | awk '{print $2}' > /app/api-key

# Your application code
COPY . /app
CMD ["node", "server.js"]

🆘 Need Help?

Documentation: Full Documentation
Issues: GitHub Issues
Discussions: GitHub Discussions
Community: Join our Discord

API authentication is optional. Your better-ccflare instance will work exactly as before until you generate your first API key.

FilesExpand file tree

API_AUTHENTICATION.md

Latest commit

History

API_AUTHENTICATION.md

File metadata and controls

API Authentication Guide

Overview

🚀 Quick Start

1. Generate Your First API Key

2. Use the API Key

🔐 Authentication Features

Secure Key Generation

Multiple Header Formats

Flexible Management

📋 CLI Commands

Generate API Keys

List API Keys

Manage API Keys

🌐 Web Dashboard

Access the API Keys Interface

Dashboard Features

🔌 REST API

API Key Management Endpoints

List All API Keys

Generate New API Key

Get API Key Statistics

Enable/Disable API Keys

🔒 Security Features

Key Storage Security

Authentication Flow

Rate Limiting & Usage Tracking

🛡️ Security Best Practices

API Key Management

Environment-Specific Keys

Access Control

⚡ Performance

Authentication Overhead

Performance Benchmark

🔄 Migration Guide

From No Authentication to Authenticated

🐛 Troubleshooting

Common Issues

API Key Not Working

Authentication Errors

Dashboard Issues

Debug Mode

📚 Reference

API Key Format

Header Priority

Path Exemptions

CLI Reference

🚀 Advanced Usage

Programmatic Key Management

Automation Scripts

Docker Integration

🆘 Need Help?