Proposal: a local front door to the Datum Cloud API (datumctl api proxy)

[scotwells]

What this is

An enhancement proposal for datumctl api proxy — a local server that gives every tool on your machine an authenticated front door to the Datum Cloud API. It forwards each request signed in as you, attaching credentials automatically and keeping them fresh, so the tools behind it never see a token, never store one, and never break when one expires:

$ datumctl api proxy --port 8001
$ curl http://127.0.0.1:8001/apis/resourcemanager.miloapis.com/v1alpha1/organizations

This PR contains only the design document (docs/enhancements/api-proxy/README.md).

Why it exists

• Local development of apps built on the platform — instead of copying short-lived tokens into .env files, a developer points the app's API base URL at the proxy once and datumctl owns authentication for the whole workday.
• Live-updating clients — dashboards, controllers, and registries keep watches open so changes appear the moment they happen; delivering those live results in real time is a hard requirement of the design, not an optimization.
• End-to-end test suites — a harness starts a proxy, reads the printed address, and points every test at it; no test process ever holds a credential.
• Scripting and exploration — curl against a local address instead of copy-pasting tokens that expire mid-investigation.

Datum's own cloud portal is the first consumer, but the friction is the same for anything built against the platform.

Key design positions the doc takes

• A faithful stand-in by default, explicit scoping on request — a bare proxy serves the whole API so development URLs match production URLs exactly; --project/--organization serve a single project or organization for short URLs. Scope is never silently inherited from the active context.
• Conservative security posture — reachable only from the local machine with no way to open it wider, standard browser defenses on and not configurable, client-supplied credentials dropped, tokens never logged and never served.
• Predictable lifecycle — the session is pinned at startup (datumctl auth switch never repoints a running proxy), the printed address doubles as a machine-readable readiness signal, and when the session dies the proxy answers with a clearly marked error that names the fix rather than imitating a platform rejection.

Review focus

The decisions most worth reviewer eyes — a bare invocation never inherits the active context (production-parity wins), local-machine-only with no override, a same-OS-user socket mode as the first fast-follow, and never retrying a platform rejection on the client's behalf — are each stated with their rationale in the section they belong to.

Companion implementation PR: #247.

🤖 Generated with Claude Code

[scotwells]

Moved to the enhancements repo, where proposal documents live: datum-cloud/enhancements#818. The companion implementation PR remains #247.