[Feature Request] Optional read-only management key for quota/usage/credential-metadata reads

[Rick7C2]

Problem

The Management API has a single credential class: the full management key (management.secret-key). It authorizes everything, including config writes, credential upload/delete, plugin install/delete, quota resets, and api-call (which executes upstream requests using stored credentials).

Tooling that only needs to observe state — credential metadata, quota/usage snapshots, plugin quota — must therefore hold the full write key. Promising to "only ever send GET requests" on the client side doesn't reduce the blast radius if that tooling is buggy or compromised: the server will happily accept writes from it.

A related operational issue: failed management authentication is counted per source IP (5 failures → 30-minute ban in AuthenticateManagementKey). A monitoring loop running on the same host with a mistyped key can lock the operator out of real management.

Proposal

Add an optional second management credential scoped to read-only operations, for example management.read-only-key (name/shape entirely up to you):

• Stored and verified the same way as secret-key (plaintext in config, hashed on startup). Empty/unset = disabled, and current behaviour is unchanged.
• It authenticates against the Management API but is authorized only for an explicit allow-list of safe read operations, enforced server-side in the shared management middleware (internal/api/handlers/management/handler.go). No changes to /v0/management endpoints themselves — enforcement would live in the middleware both route groups already share, so the read-only scope can't be bypassed via the other version prefix.
• Authentication returns the scope explicitly, so non-HTTP reuse of the verifier can never mistake a read-only credential for a full one. Logs would record the scope only, never key material.

Why an allow-list, not "GET only"

GET is not synonymous with safe in this API, so a verb check alone is not sufficient:

• GET /v8/management/credentials/download returns credential file contents.
• GET /v8/management/config, /config.yaml and /config/*path return the full configuration (and per docs/management-api-v8.md, the YAML form includes values the JSON form redacts).
• GET /v8/management/oauth/auth-url starts a login session — a state change via GET.

Those should stay denied for the read-only scope. Conversely, read-shaped POSTs that trigger upstream calls or mutate state (quota fetch, plugin quota fetch, credentials/verify, api-call) should also stay denied by default.

Suggested initial allowed set (v8 paths), open to adjustment: GET /credentials, GET /credentials/models, GET /plugins, GET /plugins/:id/quota, GET /observability/usage/api-keys, GET /observability/usage/queue, GET /routing/model-definitions/:channel, GET /server/latest-version. I'd default-deny logs and config reads as well, but that's your call. Plugin-registered management routes (the pluginManagementNoRoute fallback) would be denied for this scope unless there's a reason to do otherwise.

Enforcement detail worth deciding up front: match on the registered route template (c.FullPath()) plus method, not on raw URL prefixes, so wildcard/alias paths can't smuggle a write past the check.

Open design questions

1. Separate failure budget. Ideally, failed attempts with the read-only credential don't count toward the full key's IP ban, and vice versa. Since the server can't tell which credential a wrong key was meant to be, the clean way is for the caller to select the class explicitly (e.g. a distinct header). Would you accept that, or prefer a shared counter for simplicity?
2. Does the read-only key alone enable management routes? Today routes register once a secret key is configured. A deployment that sets only the read-only key could expose a read-only-only management surface, which seems useful for monitoring-only setups — or you may prefer to require secret-key as today.
3. Config naming/shape. management.read-only-key as a sibling of secret-key, or a more general per-key scope list if you anticipate more classes later? I'd keep it to the single optional key (KISS) unless you want the general form.

Relationship to #6972

#6972 asked for an external-scheduler mode (client API keys reading management endpoints, strict AuthID dispatch, bypassing internal scheduling) and was closed as not planned in favour of the Home control plane. This request is deliberately much narrower: no scheduling delegation, no client-key reuse, no dispatch semantics — just a second credential class for the existing Management API, for operators who run management locally (Home mode disables the local management endpoints, so it doesn't cover local read-only monitoring). Happy to be told it's still unwanted, of course.

Acceptance sketch

• With read-only-key unset, behaviour is identical to today.
• The read-only key succeeds on allow-listed reads and is rejected (403) on every other management route, including writes via the other version prefix, wildcard config paths, and plugin management routes.
• The sensitive GETs listed above are rejected for the read-only scope.
• Table-driven tests enumerate the registered management routes and assert deny-by-default; separate ban-bucket behaviour is covered depending on the answer to question 1.
• gofmt, compile check, and go test ./... pass, per AGENTS.md.

If the direction is acceptable, I'm happy to implement it as a small PR scoped to the config type, the management auth middleware, and tests, and to adjust the allow-list/semantics to your preferences first. If you'd rather not add a second credential class at all, no hard feelings — close away.

Disclosure: this issue was drafted with AI assistance and is being submitted by the account holder, who will own any follow-up PR.

[Rick7C2]

Closing this myself. Thanks for moving it to Ideas, and sorry for the noise.

• My use case changed: the tool I had in mind now needs provider quota calls through api-call, which this proposal keeps away from a read-only key. It wouldn't let me drop the full key, so I won't be sending the PR I offered.
• Re-reading current main, my suggested allow-list was wrong in at least four places, in case anyone picks this idea up later:
  • GET /observability/usage/queue pops records (redisqueue.PopOldest), so it isn't a read.
  • GET /observability/usage/api-keys keys its response by base_url|api-key, so it returns upstream API keys.
  • GET /plugins/:id/quota runs the same live FetchQuotaByPlugin call as the POST.
  • GET /credentials puts the raw key in account for API-key credentials (AccountInfo()), so it isn't metadata-only either.

Disclosure: drafted with AI assistance and posted by the account holder.