Dashboard/Scout/wiki/decisions/2026-07-03-service-key-billing-admin-metrics.md
Scout

wiki/decisions/2026-07-03-service-key-billing-admin-metrics.md

ADR: Service-Key Protected Billing Admin Metrics

Date: 2026-07-03 Status: Accepted

Context

Scout is moving from local utility into hosted beta service. The current hosted system already records tenants, API keys, purchases, credit balances, and usage ledger events, but operator visibility was split between tenant-facing hosted endpoints and SSH-only SQLite scripts. That is too hidden for a SaaS-style beta because operators need quick measurement of signups, usage, purchases, credits, and revenue without exposing secrets.

Decision

Add GET /v1/billing/admin/metrics, protected by the service X-API-Key, and allow that service-key route even when SCOUT_PUBLIC_HOSTED_ONLY=true.

Rationale

The endpoint gives Scout an operator monitoring primitive that can be used by scripts, dashboards, or future internal admin pages. It complements the tenant-facing /v1/hosted/me, /v1/hosted/usage, and /v1/hosted/purchases routes without turning tenant APIs into admin APIs.

The response is deliberately non-secret. It can include account ids, tenant ids, key ids, email, names, plan, balances, purchase package metadata, usage actions, credits consumed, and aggregate totals. It must not include raw hosted API keys, key hashes, Stripe secrets, SMTP secrets, or payment details.

Alternatives Considered

Option Why rejected
SSH-only SQLite scripts Useful for emergency operations, but too hidden for hosted beta measurement and hard to automate from other operator tools.
Public metrics endpoint Unsafe because account, usage, and purchase data belong behind operator authorization.
Tenant-only metrics Insufficient for beta operations because operators need cross-account signup, usage, purchase, and revenue totals.

Consequences

  • SCOUT_API_KEY/service key becomes the operator credential for the metrics API and must be protected like any SaaS admin credential.
  • Hosted-only middleware must continue blocking local/admin routes while explicitly allowing /v1/billing/admin/* only with the correct service key.
  • Future dashboards can build on this endpoint instead of scraping SSH command output.
  • The endpoint should remain non-secret and receive regression tests for auth boundaries and secret leakage.