Management API Overview

​

Base URL

/v0/management

​

Authentication

​

Authorization Header

curl -H "Authorization: Bearer YOUR_SECRET_KEY" \
  http://localhost:8317/v0/management/config

​

Custom Header

curl -H "X-Management-Key: YOUR_SECRET_KEY" \
  http://localhost:8317/v0/management/config

​

Security Configuration

remote-management:
  # Allow remote (non-localhost) access
  allow-remote: false
  
  # Management secret key (hashed on startup if plaintext)
  secret-key: "your-secret-key"
  
  # Disable the bundled management control panel
  disable-control-panel: false

​

Environment Variable Override

• Enable remote management automatically
• Override the config file secret key

export MANAGEMENT_PASSWORD="your-runtime-secret"
./cli-proxy-api

​

Rate Limiting

• Max failures: 5 failed authentication attempts
• Ban duration: 30 minutes
• Automatic cleanup: Stale IPs purged after 2 hours idle time

​

Response Headers

X-CPA-VERSION: v6.0.0
X-CPA-COMMIT: abc123def
X-CPA-BUILD-DATE: 2026-03-11

​

Management Endpoints

​

Configuration

• GET /v0/management/config - Get full configuration
• GET /v0/management/config.yaml - Get raw YAML config
• PUT /v0/management/config.yaml - Update entire config
• GET /v0/management/latest-version - Check for updates

​

OAuth Sessions

• POST /v0/management/oauth-callback - Handle OAuth callback
• GET /v0/management/get-auth-status - Get authentication status
• GET /v0/management/{provider}-auth-url - Get OAuth authorization URL

​

Quota Management

• GET /v0/management/quota-exceeded/switch-project - Get project switching setting
• PUT /v0/management/quota-exceeded/switch-project - Enable/disable project switching
• GET /v0/management/quota-exceeded/switch-preview-model - Get preview model switching
• PUT /v0/management/quota-exceeded/switch-preview-model - Enable/disable preview switching

​

Logs

• GET /v0/management/logs - Get log entries
• DELETE /v0/management/logs - Clear all logs
• GET /v0/management/request-error-logs - List error log files
• GET /v0/management/request-log-by-id/:id - Download request log by ID

​

Usage Statistics

• GET /v0/management/usage - Get usage statistics
• GET /v0/management/usage/export - Export usage data
• POST /v0/management/usage/import - Import usage data

​

Authentication Files

• GET /v0/management/auth-files - List authentication files
• POST /v0/management/auth-files - Upload authentication file
• DELETE /v0/management/auth-files - Delete authentication file
• GET /v0/management/auth-files/models - Get available models

​

API Keys

• GET /v0/management/api-keys - Get API keys
• PUT /v0/management/api-keys - Replace API keys
• PATCH /v0/management/api-keys - Update specific key
• DELETE /v0/management/api-keys - Delete API key

​

Provider Keys

• Gemini: /v0/management/gemini-api-key
• Claude: /v0/management/claude-api-key
• Codex: /v0/management/codex-api-key
• OpenAI Compatible: /v0/management/openai-compatibility
• Vertex: /v0/management/vertex-api-key

​

Error Responses

​

401 Unauthorized

{
  "error": "missing management key"
}

{
  "error": "invalid management key"
}

​

403 Forbidden

{
  "error": "remote management disabled"
}

{
  "error": "IP banned due to too many failed attempts. Try again in 29m 45s"
}

​

404 Not Found

​

Example: Complete Setup

# 1. Configure management in config.yaml
remote-management:
  allow-remote: false
  secret-key: "my-secure-key-123"

# 2. Start server
./cli-proxy-api -c config.yaml

# 3. Make management request
curl -H "X-Management-Key: my-secure-key-123" \
  http://localhost:8317/v0/management/config | jq

# 4. Update configuration
curl -X PUT \
  -H "X-Management-Key: my-secure-key-123" \
  -H "Content-Type: application/json" \
  -d '{"value": true}' \
  http://localhost:8317/v0/management/debug

​

Next Steps

• Configuration Endpoints - Manage server configuration
• OAuth Endpoints - Handle OAuth authentication flows
• Quota Endpoints - Configure quota behavior
• Log Endpoints - Access and manage logs