Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/router-for-me/CLIProxyAPI/llms.txt

Use this file to discover all available pages before exploring further.

The Management API provides secure endpoints for configuring and managing the CLI Proxy API server at runtime. All endpoints require authentication and can be restricted to localhost access.

​
Base URL

/v0/management

​
Authentication

All Management API requests require authentication using one of these methods:

​
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

Configure management access in config.yaml: 
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
Security Best Practices:
  • Keep allow-remote: false unless remote management is required
  • Use a strong, randomly generated secret-key
  • Even localhost requests require the management key
  • Empty secret-key disables all management routes (returns 404)

​
Environment Variable Override

Set MANAGEMENT_PASSWORD environment variable to:
  • Enable remote management automatically
  • Override the config file secret key
export MANAGEMENT_PASSWORD="your-runtime-secret"
./cli-proxy-api

​
Rate Limiting

Remote clients are subject to rate limiting:
  • Max failures: 5 failed authentication attempts
  • Ban duration: 30 minutes
  • Automatic cleanup: Stale IPs purged after 2 hours idle time

​
Response Headers

All management responses include build information: 
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
See Configuration Endpoints for details.

​
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
See OAuth Endpoints for details.

​
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
See Quota Endpoints for details.

​
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
See Log Endpoints for details.

​
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

Returned when management API is completely disabled (empty secret-key).

​
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