Management API

Base path: http://localhost:8317/v0/management

This API manages the CLI Proxy API’s runtime configuration and authentication files. All changes are persisted to the YAML config file and hot‑reloaded by the service.

Note: The following options cannot be modified via API and must be set in the config file (restart if needed):

• allow-remote-management
• remote-management-key (if plaintext is detected at startup, it is automatically bcrypt‑hashed and written back to the config)

Authentication

• All requests (including localhost) must provide a valid management key.
• Remote access requires enabling remote management in the config: allow-remote-management: true.
• Provide the management key (in plaintext) via either:
  • Authorization: Bearer <plaintext-key>
  • X-Management-Key: <plaintext-key>

Additional notes:

• If remote-management.secret-key is empty, the entire Management API is disabled (all /v0/management routes return 404).
• For remote IPs, 5 consecutive authentication failures trigger a temporary ban (~30 minutes) before further attempts are allowed.

If a plaintext key is detected in the config at startup, it will be bcrypt‑hashed and written back to the config file automatically.

Request/Response Conventions

• Content-Type: application/json (unless otherwise noted).
• Boolean/int/string updates: request body is { "value": <type> }.
• Array PUT: either a raw array (e.g. ["a","b"]) or { "items": [ ... ] }.
• Array PATCH: supports { "old": "k1", "new": "k2" } or { "index": 0, "value": "k2" }.
• Object-array PATCH: supports matching by index or by key field (specified per endpoint).

Endpoints

Usage Statistics

• GET /usage — Retrieve aggregated in-memory request metrics
  • Response:

    {
      "usage": {
        "total_requests": 24,
        "success_count": 22,
        "failure_count": 2,
        "total_tokens": 13890,
        "requests_by_day": {
          "2024-05-20": 12
        },
        "requests_by_hour": {
          "09": 4,
          "18": 8
        },
        "tokens_by_day": {
          "2024-05-20": 9876
        },
        "tokens_by_hour": {
          "09": 1234,
          "18": 865
        },
        "apis": {
          "POST /v1/chat/completions": {
            "total_requests": 12,
            "total_tokens": 9021,
            "models": {
              "gpt-4o-mini": {
                "total_requests": 8,
                "total_tokens": 7123,
                "details": [
                  {
                    "timestamp": "2024-05-20T09:15:04.123456Z",
                    "tokens": {
                      "input_tokens": 523,
                      "output_tokens": 308,
                      "reasoning_tokens": 0,
                      "cached_tokens": 0,
                      "total_tokens": 831
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "failed_requests": 2
    }

  • Notes:
    • Statistics are recalculated for every request that reports token usage; data resets when the server restarts.
    • Hourly counters fold all days into the same hour bucket (00–23).
    • The top-level failed_requests repeats usage.failure_count for convenience when polling.

Config

• GET /config — Get the full config
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/config

  • Response:

    {"debug":true,"proxy-url":"","api-keys":["1...5","JS...W"],"quota-exceeded":{"switch-project":true,"switch-preview-model":true},"gemini-api-key":[{"api-key":"AI...01","base-url":"https://generativelanguage.googleapis.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""},{"api-key":"AI...02","proxy-url":"socks5://proxy.example.com:1080"}],"generative-language-api-key":["AI...01","AI...02"],"request-log":true,"request-retry":3,"claude-api-key":[{"api-key":"cr...56","base-url":"https://example.com/api","proxy-url":"socks5://proxy.example.com:1080","models":[{"name":"claude-3-5-sonnet-20241022","alias":"claude-sonnet-latest"}]},{"api-key":"cr...e3","base-url":"http://example.com:3000/api","proxy-url":""},{"api-key":"sk-...q2","base-url":"https://example.com","proxy-url":""}],"codex-api-key":[{"api-key":"sk...01","base-url":"https://example/v1","proxy-url":""}],"openai-compatibility":[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk...01","proxy-url":""}],"models":[{"name":"moonshotai/kimi-k2:free","alias":"kimi-k2"}]},{"name":"iflow","base-url":"https://apis.iflow.cn/v1","api-key-entries":[{"api-key":"sk...7e","proxy-url":"socks5://proxy.example.com:1080"}],"models":[{"name":"deepseek-v3.1","alias":"deepseek-v3.1"},{"name":"glm-4.5","alias":"glm-4.5"},{"name":"kimi-k2","alias":"kimi-k2"}]}]}

  • Notes:
    • The response includes a sanitized gl-api-key list derived from the detailed gemini-api-key entries.
    • When no configuration is loaded yet the handler returns {}.

Debug

• GET /debug — Get the current debug state
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/debug

  • Response:

    { "debug": false }

• PUT/PATCH /debug — Set debug (boolean)
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":true}' \
      http://localhost:8317/v0/management/debug

  • Response:

    { "status": "ok" }

Config YAML

• GET /config.yaml — Download the persisted YAML file as-is
  • Response headers:
    • Content-Type: application/yaml; charset=utf-8
    • Cache-Control: no-store
  • Response body: raw YAML stream preserving comments/formatting.
• PUT /config.yaml — Replace the config with a YAML document
  • Request:

    curl -X PUT -H 'Content-Type: application/yaml' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      --data-binary @config.yaml \
      http://localhost:8317/v0/management/config.yaml

  • Response:

    { "ok": true, "changed": ["config"] }

  • Notes:
    • The server validates the YAML by loading it before persisting; invalid configs return 422 with { "error": "invalid_config", "message": "..." }.
    • Write failures return 500 with { "error": "write_failed", "message": "..." }.

Logging to File

• GET /logging-to-file — Check whether file logging is enabled
  • Response:

    { "logging-to-file": true }

• PUT/PATCH /logging-to-file — Enable or disable file logging
  • Request:

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":false}' \
      http://localhost:8317/v0/management/logging-to-file

  • Response:

    { "status": "ok" }

Log Files

• GET /logs — Stream recent log lines
  • Query params:
    • after (optional): Unix timestamp; only lines newer than this are returned.
  • Response:

    {
      "lines": ["2024-05-20 12:00:00 info request accepted"],
      "line-count": 125,
      "latest-timestamp": 1716206400
    }

  • Notes:
    • Requires file logging to be enabled; otherwise returns { "error": "logging to file disabled" } with 400.
    • When no log file exists yet the response contains empty lines and line-count: 0.
• DELETE /logs — Remove rotated log files and truncate the active log
  • Response:

    { "success": true, "message": "Logs cleared successfully", "removed": 3 }

Usage Statistics Toggle

• GET /usage-statistics-enabled — Check whether telemetry collection is active
  • Response:

    { "usage-statistics-enabled": true }

• PUT/PATCH /usage-statistics-enabled — Enable or disable collection
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":true}' \
      http://localhost:8317/v0/management/usage-statistics-enabled

  • Response:

    { "status": "ok" }

Proxy Server URL

• GET /proxy-url — Get the proxy URL string
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/proxy-url

  • Response:

    { "proxy-url": "socks5://user:[email protected]:1080/" }

• PUT/PATCH /proxy-url — Set the proxy URL string
  • Request (PUT):

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":"socks5://user:[email protected]:1080/"}' \
      http://localhost:8317/v0/management/proxy-url

  • Request (PATCH):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":"http://127.0.0.1:8080"}' \
      http://localhost:8317/v0/management/proxy-url

  • Response:

    { "status": "ok" }

• DELETE /proxy-url — Clear the proxy URL
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE http://localhost:8317/v0/management/proxy-url

  • Response:

    { "status": "ok" }

Quota Exceeded Behavior

• GET /quota-exceeded/switch-project
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-project

  • Response:

    { "switch-project": true }

• PUT/PATCH /quota-exceeded/switch-project — Boolean
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":false}' \
      http://localhost:8317/v0/management/quota-exceeded/switch-project

  • Response:

    { "status": "ok" }

• GET /quota-exceeded/switch-preview-model
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-preview-model

  • Response:

    { "switch-preview-model": true }

• PUT/PATCH /quota-exceeded/switch-preview-model — Boolean
  • Request:

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":true}' \
      http://localhost:8317/v0/management/quota-exceeded/switch-preview-model

  • Response:

    { "status": "ok" }

API Keys (proxy service auth)

These endpoints update the inline config-api-key provider inside the auth.providers section of the configuration. Legacy top-level api-keys remain in sync automatically.

• GET /api-keys — Return the full list
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/api-keys

  • Response:

    { "api-keys": ["k1","k2","k3"] }

• PUT /api-keys — Replace the full list
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '["k1","k2","k3"]' \
      http://localhost:8317/v0/management/api-keys

  • Response:

    { "status": "ok" }

• PATCH /api-keys — Modify one item (old/new or index/value)
  • Request (by old/new):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"old":"k2","new":"k2b"}' \
      http://localhost:8317/v0/management/api-keys

  • Request (by index/value):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"index":0,"value":"k1b"}' \
      http://localhost:8317/v0/management/api-keys

  • Response:

    { "status": "ok" }

• DELETE /api-keys — Delete one (?value= or ?index=)
  • Request (by value):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1'

  • Request (by index):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/api-keys?index=0'

  • Response:

    { "status": "ok" }

Gemini API Key

• GET /gemini-api-key
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/gemini-api-key

  • Response:

    {
      "gemini-api-key": [
        {"api-key":"AIzaSy...01","base-url":"https://generativelanguage.googleapis.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""},
        {"api-key":"AIzaSy...02","proxy-url":"socks5://proxy.example.com:1080"}
      ]
    }

• PUT /gemini-api-key
  • Request (array form):

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '[{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"vendor-value"}},{"api-key":"AIzaSy-2","base-url":"https://custom.example.com"}]' \
      http://localhost:8317/v0/management/gemini-api-key

  • Response:

    { "status": "ok" }

• PATCH /gemini-api-key
  • Request (update by index):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"index":0,"value":{"api-key":"AIzaSy-1","base-url":"https://custom.example.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":""}}' \
      http://localhost:8317/v0/management/gemini-api-key

  • Request (update by api-key match):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"match":"AIzaSy-1","value":{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"custom-value"},"proxy-url":"socks5://proxy.example.com:1080"}}' \
      http://localhost:8317/v0/management/gemini-api-key

  • Response:

    { "status": "ok" }

• DELETE /gemini-api-key
  • Request (by api-key):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE \
      'http://localhost:8317/v0/management/gemini-api-key?api-key=AIzaSy-1'

  • Request (by index):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE \
      'http://localhost:8317/v0/management/gemini-api-key?index=0'

  • Response:

    { "status": "ok" }

Generative Language API Key (Legacy Alias)

• GET /generative-language-api-key
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/generative-language-api-key

  • Response:

    { "generative-language-api-key": ["AIzaSy...01","AIzaSy...02"] }

• PUT /generative-language-api-key
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '["AIzaSy-1","AIzaSy-2"]' \
      http://localhost:8317/v0/management/generative-language-api-key

  • Response:

    { "status": "ok" }

• PATCH /generative-language-api-key
  • Request:

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"old":"AIzaSy-1","new":"AIzaSy-1b"}' \
      http://localhost:8317/v0/management/generative-language-api-key

  • Response:

    { "status": "ok" }

• DELETE /generative-language-api-key
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/generative-language-api-key?value=AIzaSy-2'

  • Response:

    { "status": "ok" }

• Notes:
  • This endpoint mirrors the key-only view of gemini-api-key.

Codex API KEY (object array)

• GET /codex-api-key — List all
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/codex-api-key

  • Response:

    { "codex-api-key": [ { "api-key": "sk-a", "base-url": "", "proxy-url": "" } ] }

• PUT /codex-api-key — Replace the list
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080"},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":""}]' \
      http://localhost:8317/v0/management/codex-api-key

  • Response:

    { "status": "ok" }

• PATCH /codex-api-key — Modify one (by index or match)
  • Request (by index):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":""}}' \
      http://localhost:8317/v0/management/codex-api-key

  • Request (by match):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080"}}' \
      http://localhost:8317/v0/management/codex-api-key

  • Response:

    { "status": "ok" }

• DELETE /codex-api-key — Delete one (?api-key= or ?index=)
  • Request (by api-key):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2'

  • Request (by index):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?index=0'

  • Response:

    { "status": "ok" }

Request Retry Count

• GET /request-retry — Get integer
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-retry

  • Response:

    { "request-retry": 3 }

• PUT/PATCH /request-retry — Set integer
  • Request:

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":5}' \
      http://localhost:8317/v0/management/request-retry

  • Response:

    { "status": "ok" }

Request Log

• GET /request-log — Get boolean
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-log

  • Response:

    { "request-log": false }

• PUT/PATCH /request-log — Set boolean
  • Request:

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"value":true}' \
      http://localhost:8317/v0/management/request-log

  • Response:

    { "status": "ok" }

Claude API KEY (object array)

• GET /claude-api-key — List all
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/claude-api-key

  • Response:

    { "claude-api-key": [ { "api-key": "sk-a", "base-url": "", "proxy-url": "" } ] }

• PUT /claude-api-key — Replace the list
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080"},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":""}]' \
      http://localhost:8317/v0/management/claude-api-key

  • Response:

    { "status": "ok" }

• PATCH /claude-api-key — Modify one (by index or match)
  • Request (by index):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
        -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":""}}' \
        http://localhost:8317/v0/management/claude-api-key

  • Request (by match):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
        -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080"}}' \
        http://localhost:8317/v0/management/claude-api-key

  • Response:

    { "status": "ok" }

• DELETE /claude-api-key — Delete one (?api-key= or ?index=)
  • Request (by api-key):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2'

  • Request (by index):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?index=0'

  • Response:

    { "status": "ok" }

OpenAI Compatibility Providers (object array)

• GET /openai-compatibility — List all
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/openai-compatibility

  • Response:

    { "openai-compatibility": [ { "name": "openrouter", "base-url": "https://openrouter.ai/api/v1", "api-key-entries": [ { "api-key": "sk", "proxy-url": "" } ], "models": [] } ] }

• PUT /openai-compatibility — Replace the list
  • Request:

    curl -X PUT -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[{"name":"m","alias":"a"}]}]' \
      http://localhost:8317/v0/management/openai-compatibility

  • Response:

    { "status": "ok" }

• PATCH /openai-compatibility — Modify one (by index or name)

  • Request (by name):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[]}}' \
      http://localhost:8317/v0/management/openai-compatibility

  • Request (by index):

    curl -X PATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d '{"index":0,"value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[]}}' \
      http://localhost:8317/v0/management/openai-compatibility

  • Response:

    { "status": "ok" }

  • Notes:

    • Legacy api-keys input remains accepted; keys are migrated into api-key-entries automatically so the legacy field will eventually remain empty in responses.
• DELETE /openai-compatibility — Delete (?name= or ?index=)
  • Request (by name):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?name=openrouter'

  • Request (by index):

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0'

  • Response:

    { "status": "ok" }

Auth File Management

Manage JSON token files under auth-dir: list, download, upload, delete.

• GET /auth-files — List

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/auth-files

  • Response:

    { "files": [ { "name": "acc1.json", "size": 1234, "modtime": "2025-08-30T12:34:56Z", "type": "google", "email": "[email protected]" } ] }

  • Notes:
    • modtime is returned in RFC3339 format; when metadata includes an email it is surfaced.

• GET /auth-files/download?name=<file.json> — Download a single file

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -OJ 'http://localhost:8317/v0/management/auth-files/download?name=acc1.json'

• POST /auth-files — Upload

  • Request (multipart):

    curl -X POST -F 'file=@/path/to/acc1.json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      http://localhost:8317/v0/management/auth-files

  • Request (raw JSON):

    curl -X POST -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      -d @/path/to/acc1.json \
      'http://localhost:8317/v0/management/auth-files?name=acc1.json'

  • Response:

    { "status": "ok" }

  • Notes:
    • The core auth manager must be active; otherwise the API returns 503 with { "error": "core auth manager unavailable" }.
    • Uploaded filenames must end with .json.

• DELETE /auth-files?name=<file.json> — Delete a single file

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?name=acc1.json'

  • Response:

    { "status": "ok" }

• DELETE /auth-files?all=true — Delete all .json files under auth-dir

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' -X DELETE 'http://localhost:8317/v0/management/auth-files?all=true'

  • Response:

    { "status": "ok", "deleted": 3 }

Login/OAuth URLs

These endpoints initiate provider login flows and return a URL to open in a browser. Tokens are saved under auths/ once the flow completes.

For Anthropic, Codex, Gemini CLI, and iFlow you can append ?is_webui=true to reuse the embedded callback forwarder when launching from the management UI.

• GET /anthropic-auth-url — Start Anthropic (Claude) login

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      http://localhost:8317/v0/management/anthropic-auth-url

  • Response:

    { "status": "ok", "url": "https://...", "state": "anth-1716206400" }

  • Notes:
    • Add ?is_webui=true when triggering from the built-in UI to reuse the local callback service.

• GET /codex-auth-url — Start Codex login

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      http://localhost:8317/v0/management/codex-auth-url

  • Response:

    { "status": "ok", "url": "https://...", "state": "codex-1716206400" }

• GET /gemini-cli-auth-url — Start Google (Gemini CLI) login

  • Query params:
    • project_id (optional): Google Cloud project ID.
  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      'http://localhost:8317/v0/management/gemini-cli-auth-url?project_id=<PROJECT_ID>'

  • Response:

    { "status": "ok", "url": "https://...", "state": "gem-1716206400" }

• GET /qwen-auth-url — Start Qwen login (device flow)

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      http://localhost:8317/v0/management/qwen-auth-url

  • Response:

    { "status": "ok", "url": "https://...", "state": "gem-1716206400" }

• GET /iflow-auth-url — Start iFlow login

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      http://localhost:8317/v0/management/iflow-auth-url

  • Response:

    { "status": "ok", "url": "https://...", "state": "ifl-1716206400" }

• GET /get-auth-status?state=<state> — Poll OAuth flow status

  • Request:

    curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
      'http://localhost:8317/v0/management/get-auth-status?state=<STATE_FROM_AUTH_URL>'

  • Response examples:

    { "status": "wait" }

    { "status": "ok" }

    { "status": "error", "error": "Authentication failed" }

Error Responses

Generic error format:

• 400 Bad Request: { "error": "invalid body" }
• 401 Unauthorized: { "error": "missing management key" } or { "error": "invalid management key" }
• 403 Forbidden: { "error": "remote management disabled" }
• 404 Not Found: { "error": "item not found" } or { "error": "file not found" }
• 422 Unprocessable Entity: { "error": "invalid_config", "message": "..." }
• 500 Internal Server Error: { "error": "failed to save config: ..." }
• 503 Service Unavailable: { "error": "core auth manager unavailable" }

Notes

• Changes are written back to the YAML config file and hot‑reloaded by the file watcher and clients.
• allow-remote-management and remote-management-key cannot be changed via the API; configure them in the config file.