API Key Management

Created: Tue 29 Jul 2025 10:45:00 CEST
Document Version: 1.0 - Initial security documentation
Security Classification: Internal Security Documentation
Target Audience: DevOps Engineers, Security Team, System Administrators
Author: Paul Wisén

Overview

This document describes the secure generation and management of API keys for the Plings ecosystem, specifically for service-to-service authentication between the Director (s.plings.io) and Backend API (api.plings.io).

Security Principles

  1. Never generate API keys in chat systems (Claude, ChatGPT, etc.)
  2. Never commit API keys to version control
  3. Rotate keys regularly (recommended: every 90 days)
  4. Use different keys for each environment (dev, staging, production)
  5. Monitor key usage for anomalies

Generating Secure API Keys

# Generate a 64-character hex string
openssl rand -hex 32

# Add the dir_ prefix for Director keys
echo "dir_$(openssl rand -hex 32)"

Method 2: Using Python

import secrets
api_key = f"dir_{secrets.token_hex(32)}"
print(api_key)

Method 3: Using Node.js

const crypto = require('crypto');
const apiKey = `dir_${crypto.randomBytes(32).toString('hex')}`;
console.log(apiKey);

Key Format Standards

Director API Keys

Future Key Types

Configuration Locations

Director Service (s.plings.io)

  1. Vercel Dashboard: https://vercel.com/[your-team]/plings-director/settings/environment-variables
  2. Variable Name: DIRECTOR_API_KEY
  3. Environments: Set for Production, Preview, and Development separately

Backend API (api.plings.io)

  1. Vercel Dashboard: https://vercel.com/[your-team]/plings-backend/settings/environment-variables
  2. Variable Name: DIRECTOR_API_KEY (optional override)
  3. Default: Uses built-in development key if not set

Key Storage in Backend

The backend stores only the first 12 characters of the SHA256 hash of API keys:

import hashlib

def hash_api_key(api_key: str) -> str:
    """Hash an API key for storage/comparison."""
    return hashlib.sha256(api_key.encode()).hexdigest()[:12]

This ensures that even if the backend database is compromised, the actual API keys cannot be recovered.

Key Rotation Process

1. Generate New Key

NEW_KEY="dir_$(openssl rand -hex 32)"
echo "New API Key: $NEW_KEY"
echo "Hash for backend: $(echo -n $NEW_KEY | shasum -a 256 | cut -c1-12)"

2. Update Backend First

Add the new key hash to director_auth.py:

DIRECTOR_API_KEYS = {
    "new_hash_here": {
        "name": "director-prod-v2",
        "created": "2025-MM-DD",
        "active": True
    },
    # Keep old key active during transition
    "old_hash_here": {
        "name": "director-prod-v1",
        "created": "2025-MM-DD",
        "active": True
    }
}

3. Deploy Backend

Deploy the backend with both keys active.

4. Update Director

Update the DIRECTOR_API_KEY environment variable in Vercel.

5. Verify New Key

Test the Director service with the new key.

6. Deactivate Old Key

After verification, set the old key’s active to False in the backend.

Security Monitoring

What to Monitor

  1. Failed authentication attempts - Multiple failures may indicate attempted breach
  2. Unusual request patterns - Spike in requests or unusual times
  3. Geographic anomalies - Requests from unexpected locations
  4. Rate limit violations - May indicate abuse

Logging Requirements

All API key usage should be logged with:

Emergency Procedures

If a Key is Compromised

  1. Immediately deactivate the key in the backend
  2. Generate a new key using the secure methods above
  3. Update all services using the compromised key
  4. Review logs for unauthorized usage
  5. Notify security team and stakeholders

Backend Emergency Override

If all keys are compromised, the backend can be temporarily configured to reject all Director requests:

# In director_auth.py
EMERGENCY_LOCKDOWN = True  # Set via environment variable

Best Practices

  1. Environment-Specific Keys: Never use production keys in development
  2. Least Privilege: Each service should have only the permissions it needs
  3. Regular Audits: Review active keys quarterly
  4. Documentation: Keep a secure record of which keys are used where
  5. No Hardcoding: Always use environment variables

Compliance Notes