API Authentication

This guide covers configuring API authentication for License Monitor to secure access to endpoints.

Authentication Methods

License Monitor supports multiple authentication methods:

Method	Use Case	Configuration
API Key (Header)	Server-to-server	X-API-Key header
API Key (Query)	WebSocket/SSE	?api_key= parameter
Bearer Token	JWT integration	Authorization: Bearer

API Key Authentication

Generating API Keys

Generate a secure API key:

OpenSSL

openssl rand -hex 32
# Output: a1b2c3d4e5f6...

Python

import secrets
print(secrets.token_hex(32))

Node.js

const crypto = require('crypto');
console.log(crypto.randomBytes(32).toString('hex'));

Configuration

Configure API key authentication in config.toml:

[api]
enabled = true
bind_address = "127.0.0.1"
bind_port = 8080

# API Key Configuration
api_key = "your-secure-api-key-here"
require_auth = true

Or via environment variable:

export LICENSE_MONITOR_API_KEY="your-secure-api-key-here"

Using API Keys

Header Authentication (Recommended)

# Using X-API-Key header
curl -H "X-API-Key: your-api-key" \
     http://localhost:8080/api/health

# Using Authorization header
curl -H "Authorization: ApiKey your-api-key" \
     http://localhost:8080/api/health

Query Parameter (WebSocket/SSE)

# For WebSocket connections
wscat -c "ws://localhost:8080/ws/logs?api_key=your-api-key"

# For SSE connections
curl "http://localhost:8080/stream/logs?api_key=your-api-key"

Caution

Avoid using query parameter authentication for REST API calls as the key may be logged in server access logs. Use header-based authentication instead.

Client Implementation

JavaScript/TypeScript

const API_KEY = process.env.LICENSE_MONITOR_API_KEY;
const BASE_URL = 'http://localhost:8080';

// REST API calls
async function fetchHealth() {
  const response = await fetch(`${BASE_URL}/api/health`, {
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
  });
  return response.json();
}

// WebSocket connection
const ws = new WebSocket(`${BASE_URL}/ws/logs?api_key=${API_KEY}`);
ws.onmessage = (event) => {
  console.log('Received:', JSON.parse(event.data));
};

// SSE connection
const eventSource = new EventSource(
  `${BASE_URL}/stream/logs?api_key=${API_KEY}`
);
eventSource.onmessage = (event) => {
  console.log('Received:', JSON.parse(event.data));
};

Python

import requests
import os

API_KEY = os.environ.get('LICENSE_MONITOR_API_KEY')
BASE_URL = 'http://localhost:8080'

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

# GET request
response = requests.get(f'{BASE_URL}/api/health', headers=headers)
print(response.json())

# POST request
response = requests.post(
    f'{BASE_URL}/api/execute',
    headers=headers,
    json={'command': 'lmstat', 'args': ['-a']}
)
print(response.json())

cURL Examples

# Health check
curl -X GET \
     -H "X-API-Key: $LICENSE_MONITOR_API_KEY" \
     http://localhost:8080/api/health

# Get licenses
curl -X GET \
     -H "X-API-Key: $LICENSE_MONITOR_API_KEY" \
     http://localhost:8080/api/licenses

# Execute command
curl -X POST \
     -H "X-API-Key: $LICENSE_MONITOR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"command": "lmstat", "args": ["-a"]}' \
     http://localhost:8080/api/execute

Multiple API Keys

For environments requiring different access levels:

[api]
# Primary API key for full access
api_key = "primary-admin-key"

# Read-only API key
api_key_readonly = "readonly-monitoring-key"

# Webhook API key
api_key_webhook = "webhook-integration-key"

Key Permissions

Key Type	Endpoints	Methods
Primary	All	GET, POST
Read-only	/api/health, /api/licenses, /api/status	GET
Webhook	/api/webhook/*	POST

Key Rotation

Rotation Procedure

1. Generate new key

   NEW_KEY=$(openssl rand -hex 32)
   echo "New key: $NEW_KEY"

2. Update configuration

   # Update config file or environment
   sed -i "s/api_key = .*/api_key = \"$NEW_KEY\"/" /etc/license-monitor/config.toml

3. Restart service

   systemctl restart license-monitor

4. Update clients

   • Update all client applications with new key
   • Verify connectivity

5. Revoke old key

   • Remove old key from all configurations
   • Monitor for failed authentication attempts

Graceful Rotation

For zero-downtime rotation, support multiple active keys temporarily:

[api]
# Support both old and new keys during rotation
api_keys = [
    "new-api-key-12345",
    "old-api-key-67890"  # Remove after rotation complete
]

Authentication Failures

Response Codes

Code	Description	Action
401	Missing or invalid API key	Provide valid key
403	Key valid but insufficient permissions	Use key with proper permissions
429	Rate limit exceeded	Reduce request rate

Error Response Format

{
  "error": "Unauthorized",
  "code": "AUTH_FAILED",
  "message": "Invalid or missing API key",
  "requestId": "req-12345"
}

Monitoring Auth Failures

# View authentication failures in logs
grep "AUTH_FAILED" /var/log/license-monitor/license_monitor.log

# Count failures by IP
grep "AUTH_FAILED" /var/log/license-monitor/license_monitor.log | \
    awk '{print $NF}' | sort | uniq -c | sort -rn

Security Best Practices

1. Never commit API keys to version control
2. Use environment variables or secrets manager
3. Rotate keys regularly (every 90 days recommended)
4. Use different keys for different environments
5. Monitor authentication failures and alert on anomalies
6. Use TLS for all API communications
7. Implement IP whitelisting where possible

Service Account Setup

For automated integrations, create dedicated service accounts:

# Create service-specific key
SERVICE_KEY=$(openssl rand -hex 32)

# Document the key purpose
cat >> /etc/license-monitor/api-keys.md << EOF
## Monitoring Service Key
- Created: $(date)
- Purpose: Prometheus metrics collection
- Permissions: Read-only
- Key prefix: ${SERVICE_KEY:0:8}...
EOF

# Store securely
echo "MONITORING_API_KEY=$SERVICE_KEY" >> /etc/license-monitor/service-keys.env

Tip

Store only key prefixes in documentation. Keep full keys in a secrets manager or encrypted storage.

Next Steps

• Network Security - IP whitelisting and firewalls
• Rate Limiting - Request throttling
• CORS Configuration - Cross-origin settings