mcphub/docs/API_KEYS_GUIDE.md

# 🔐 API Keys Management Guide

Complete guide for managing API keys in MCP Hub.

---

## Table of Contents

- [Overview](#overview)
- [Key Types](#key-types)
- [Scopes & Permissions](#scopes--permissions)
- [Creating Keys](#creating-keys)
- [Managing Keys](#managing-keys)
- [Best Practices](#best-practices)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)

---

## Overview

MCP Hub supports two types of API keys for authentication:

1. **Master API Key** - Full access to all operations and projects
2. **Per-Project API Keys** - Scoped access with granular permissions

Per-project keys provide:
- ✅ **Project-level isolation** - Limit access to specific projects
- ✅ **Scope-based permissions** - Control read/write/admin operations
- ✅ **Expiration support** - Automatic key rotation
- ✅ **Usage tracking** - Monitor key usage and last access
- ✅ **Audit trail** - All key operations are logged
- ✅ **Easy rotation** - Rotate all keys for a project with one command

---

## Key Types

### Master API Key

- **Source**: `MASTER_API_KEY` environment variable
- **Access Level**: Full admin access to all projects
- **Use Case**: Server administration, initial setup
- **Lifetime**: Permanent (until manually changed)
- **Format**: Any string (recommended: 32+ characters)

**Example**:
```bash
MASTER_API_KEY=your_secure_master_key_here
```

### Per-Project API Keys

- **Storage**: JSON file (`data/api_keys.json`)
- **Access Level**: Configurable per key (read/write/admin)
- **Use Case**: Application integration, team access, CI/CD
- **Lifetime**: Optional expiration (days)
- **Format**: `cmp_` prefix + random string

**Example**:
```
cmp_AQECAHhoZXJlIGlzIGEgcmFuZG9tIGtleQ
```

---

## Scopes & Permissions

### Read Scope

**Per-Project Keys** (`project_id` specific):
- ✅ List and get operations for assigned project
- ✅ Read WordPress content (posts, pages, comments, media)
- ✅ Read WooCommerce data (products, orders, customers)
- ✅ Read taxonomies, menus, and settings
- ❌ Cannot access system tools (requires global key)
- ❌ Cannot create, update, or delete

**Tools Allowed**:
- `wordpress_list_posts`, `wordpress_get_post`
- `wordpress_list_products`, `wordpress_get_product`
- `wordpress_list_orders`, `wordpress_get_order`
- All WordPress/WooCommerce `get_*` and `list_*` tools

**Global Keys** (`project_id="*"`):
- ✅ All per-project permissions for ALL projects
- ✅ System tools: `list_projects`, `get_project_info`
- ✅ Monitoring: `check_all_projects_health`, `get_system_metrics`
- ✅ Rate limits: `get_rate_limit_stats`
- ✅ API Keys: `manage_api_keys_list` (read-only)

**Use Cases**:
- **Per-Project**: Client access to their specific site
- **Global**: Admin dashboards, monitoring, analytics

### Write Scope

**Per-Project Keys**:
- ✅ All read operations for assigned project
- ✅ Create, update, delete content
- ✅ Upload and modify media
- ✅ Manage products, orders, customers
- ❌ Cannot access system tools (requires global key)
- ❌ Cannot manage API keys or system settings

**Tools Allowed**:
- All read scope tools for the project, plus:
- `wordpress_create_post`, `wordpress_update_post`, `wordpress_delete_post`
- `wordpress_create_product`, `wordpress_update_product`
- `wordpress_create_order`, `wordpress_update_order_status`
- `wordpress_upload_media_from_url`
- All `create_*`, `update_*`, `delete_*` tools for the project

**Global Keys** (`project_id="*"`):
- ✅ All per-project permissions for ALL projects
- ✅ System tools access (read-only)

**Use Cases**:
- **Per-Project**: Client content management for their site
- **Global**: Multi-site management, automated publishing

### Admin Scope

**Per-Project Keys**:
- ✅ All read and write operations for assigned project
- ✅ Advanced WordPress management (WP-CLI tools)
- ✅ Database operations (check, optimize, export)
- ❌ Cannot access system tools (requires global key)
- ❌ Cannot manage API keys (requires global key)

**Global Keys** (`project_id="*"`):
- ✅ All per-project permissions for ALL projects
- ✅ Full system access: `manage_api_keys_*`, `reset_rate_limit`
- ✅ System monitoring and administration
- ✅ Health metrics export

**Tools Allowed**:
- All read and write scope tools, plus:
- `manage_api_keys_*` tools (global keys only)
- `reset_rate_limit` (global keys only)
- `export_health_metrics`
- WP-CLI tools: `wp_cache_flush`, `wp_db_optimize`, etc.

**Use Cases**:
- **Per-Project**: Full site administration for specific client
- **Global**: Platform administration, multi-tenant management
- System maintenance

---

## Creating Keys

### Basic Key Creation

Create a read-only key for a specific project:

```python
result = manage_api_keys_create(
    project_id="wordpress_site1",
    scope="read"
)

# Save the key - it won't be shown again!
api_key = result["key"]  # cmp_...
key_id = result["key_id"]  # key_...
```

### Key with Description

Add a description for better organization:

```python
result = manage_api_keys_create(
    project_id="wordpress_site1",
    scope="write",
    description="CI/CD pipeline key for automated deployments"
)
```

### Expiring Key

Create a temporary key that expires after 30 days:

```python
result = manage_api_keys_create(
    project_id="wordpress_site2",
    scope="read",
    expires_in_days=30,
    description="Temporary access for contractor"
)
```

### Global Key

Create a key that works for all projects:

```python
result = manage_api_keys_create(
    project_id="*",  # All projects
    scope="admin",
    description="Backup admin key"
)
```

---

## Managing Keys

### List All Keys

```python
result = manage_api_keys_list()

print(f"Total keys: {result['total']}")
for key in result['keys']:
    print(f"- {key['key_id']}: {key['project_id']} ({key['scope']})")
```

### List Keys for Specific Project

```python
result = manage_api_keys_list(
    project_id="wordpress_site1"
)
```

### Include Revoked Keys

```python
result = manage_api_keys_list(
    include_revoked=True
)
```

### Get Key Information

```python
result = manage_api_keys_get_info(
    key_id="key_abc123"
)

if result['success']:
    key_info = result['key']
    print(f"Project: {key_info['project_id']}")
    print(f"Scope: {key_info['scope']}")
    print(f"Created: {key_info['created_at']}")
    print(f"Last used: {key_info['last_used_at']}")
    print(f"Usage count: {key_info['usage_count']}")
    print(f"Valid: {key_info['valid']}")
```

### Revoke a Key

Soft delete (can view in history):

```python
result = manage_api_keys_revoke(
    key_id="key_abc123"
)
```

### Delete a Key

Permanent deletion:

```python
result = manage_api_keys_delete(
    key_id="key_abc123"
)
```

### Rotate All Project Keys

Create new keys and revoke old ones:

```python
result = manage_api_keys_rotate(
    project_id="wordpress_site1"
)

# Save the new keys!
for new_key in result['new_keys']:
    print(f"New key: {new_key['key']}")
    print(f"Scope: {new_key['scope']}")
```

---

## Best Practices

### 1. Use Principle of Least Privilege

**❌ Don't**:
```python
# Giving admin access when read is enough
manage_api_keys_create("wordpress_site1", scope="admin")
```

**✅ Do**:
```python
# Use minimal required scope
manage_api_keys_create("wordpress_site1", scope="read")
```

### 2. Set Expiration for Temporary Access

**❌ Don't**:
```python
# Permanent key for temporary contractor
manage_api_keys_create("wordpress_site1", scope="write")
```

**✅ Do**:
```python
# Expiring key for contractor
manage_api_keys_create(
    "wordpress_site1",
    scope="write",
    expires_in_days=90,
    description="Q4 contractor access"
)
```

### 3. Use Descriptive Names

**❌ Don't**:
```python
manage_api_keys_create("wordpress_site1", "write")
```

**✅ Do**:
```python
manage_api_keys_create(
    "wordpress_site1",
    scope="write",
    description="Production deployment key for CI/CD pipeline"
)
```

### 4. Regular Key Rotation

Rotate keys quarterly or after team changes:

```python
# Every 3 months
result = manage_api_keys_rotate("wordpress_site1")

# Update all integrations with new keys
for key in result['new_keys']:
    # Update CI/CD, monitoring tools, etc.
    update_integration(key['key'])
```

### 5. Monitor Key Usage

```python
# Check if keys are being used
result = manage_api_keys_list()

for key in result['keys']:
    if key['usage_count'] == 0:
        print(f"Warning: Key {key['key_id']} has never been used")

    if key['last_used_at']:
        # Check if key hasn't been used in 30+ days
        # Consider revoking inactive keys
        pass
```

### 6. Revoke Compromised Keys Immediately

```python
# If a key is compromised
manage_api_keys_revoke("key_compromised")

# Create a new key
new_key = manage_api_keys_create(
    "wordpress_site1",
    scope="write",
    description="Replacement for compromised key"
)
```

---

## Examples

### Example 1: CI/CD Pipeline

```python
# 1. Create a write-scoped key for CI/CD
result = manage_api_keys_create(
    project_id="wordpress_site1",
    scope="write",
    description="GitHub Actions deployment key"
)

ci_key = result['key']

# 2. Add to GitHub Secrets as MCP_API_KEY

# 3. Use in workflow:
# headers = {"Authorization": f"Bearer {os.getenv('MCP_API_KEY')}"}
```

### Example 2: Monitoring Dashboard

```python
# Create read-only key for monitoring
result = manage_api_keys_create(
    project_id="*",  # All projects
    scope="read",
    description="Grafana monitoring dashboard"
)

monitoring_key = result['key']

# Use for health checks, metrics collection
```

### Example 3: Team Member Access

```python
# Create keys for team members
team_keys = {}

for member in ["alice", "bob", "charlie"]:
    result = manage_api_keys_create(
        project_id="wordpress_site1",
        scope="write",
        description=f"Key for {member}"
    )
    team_keys[member] = result['key']

# Distribute keys securely (1Password, etc.)
```

### Example 4: Temporary Contractor Access

```python
# 90-day expiring key for contractor
result = manage_api_keys_create(
    project_id="wordpress_site2",
    scope="read",
    expires_in_days=90,
    description="Contractor access - expires Q1 2026"
)

contractor_key = result['key']

# Key automatically becomes invalid after 90 days
```

### Example 5: Key Rotation Schedule

```python
# Quarterly rotation script
import schedule

def rotate_all_projects():
    projects = ["wordpress_site1", "wordpress_site2", "wordpress_site3"]

    for project in projects:
        result = manage_api_keys_rotate(project)
        print(f"Rotated {result['rotated_count']} keys for {project}")

        # Email new keys to team
        notify_team(project, result['new_keys'])

# Run every 90 days
schedule.every(90).days.do(rotate_all_projects)
```

---

## Troubleshooting

### Key Not Working

**Problem**: API key returns "Authentication failed"

**Solutions**:

1. Check if key is revoked:
```python
info = manage_api_keys_get_info("key_abc123")
if info['key']['revoked']:
    print("Key has been revoked")
```

2. Check if key expired:
```python
if info['key']['expired']:
    print("Key has expired")
```

3. Verify scope matches operation:
```python
# Read-only key cannot write
if info['key']['scope'] == 'read':
    print("Cannot use read key for write operations")
```

### Key Not Found

**Problem**: "Key not found: key_abc123"

**Solution**: List all keys to find correct ID:
```python
result = manage_api_keys_list(include_revoked=True)
for key in result['keys']:
    print(f"{key['key_id']}: {key['description']}")
```

### Permission Denied

**Problem**: "Insufficient scope"

**Solution**: Check required scope for operation:
```python
# Operation requires 'write' but key has 'read'
# Create new key with correct scope:
manage_api_keys_create(project_id="site1", scope="write")
```

### Storage File Issues

**Problem**: "Failed to load keys" or "Failed to save keys"

**Solutions**:

1. Check file permissions:
```bash
ls -l data/api_keys.json
chmod 600 data/api_keys.json  # Read/write for owner only
```

2. Check directory exists:
```bash
mkdir -p data
```

3. Validate JSON format:
```bash
python -m json.tool data/api_keys.json
```

---

## Security Considerations

### Storage Security

- API keys are stored as SHA256 hashes
- Only the key hash is saved, not the actual key
- Storage file should have restricted permissions (600)
- Consider encrypting the storage file at rest

### Network Security

- Always use HTTPS for API requests
- Never log API keys in plain text
- Use secure channels to distribute keys (1Password, Vault)

### Audit & Compliance

- All key operations are logged in audit.log
- Track key usage via `usage_count` and `last_used_at`
- Regular review of active keys
- Compliance with GDPR, SOC 2, ISO 27001

---

## Related Documentation

- [Authentication Guide](AUTH_GUIDE.md)
- [Security Policy](../SECURITY.md)
- [Audit Logging](AUDIT_LOGGING.md)
- [Rate Limiting](RATE_LIMITING.md)

---

**Version**: 1.0.0
**Last Updated**: 2025-11-11
**Maintained by**: Airano (https://mcphub.dev)