[Control-Plane] Better API control and multiple keys

[pocesar]

Summary

Both API and dashboard share a single global API_KEY.
This makes it very insecure since this single key that can start runs also allows to read full DAG and logs data that otherwise would be expected to be private. Agents also need to share the same key for communicating with each other. A compromise of any agent deployed on different machines means it now has wide access to all data.

Alternatives are to use external WAF access rules or 3rd-party reverse proxies just to be able to gate access using multiple keys to avoid exposing/sharing the global key.

Proposed solution

Add the ability for multiple virtual keys that can be scoped to exact routes and access. Keep only the admin token that is needed for client-side admin auth inside the UI.

• UI access
  • Runs
  • Queue
  • Logs
  • Input
  • Output
  • Triggers
  • Playground
• API access
  • Control executions: start, stop, pause
  • Fetch logs
  • Fetch DAG and specific fields
  • Readonly flavors

Alternatives considered

Cloud load balancing with multiple matching rules and manual key generation and hashing.

Additional context

[AbirAbbas]

Thanks for writing this up — the complaint is accurate and nothing about it has changed since May. Where things stand on main (v0.1.135-rc.1) so nobody has to read the code to find out:

Today there is exactly one API key. AGENTFIELD_API_KEY (or AGENTFIELD_API_AUTH_API_KEY) is checked by a single global middleware (internal/server/middleware/auth.go) with one constant-time compare and no route or scope map. On success it sets auth_level: api_key, on failure auth_level: public — those two values are the whole authorization vocabulary. The web UI authenticates with that same key, and SDK agents use it too. So yes: start-a-run, read-the-DAG, read logs, install packages, read/write the secret store are all one credential, and there is no key store — no api_keys table, no migration for one.

What partial separation exists:

• AGENTFIELD_AUTHORIZATION_ADMIN_TOKEN — a separate token sent as X-Admin-Token. It only gates the DID-authorization admin routes (and only when AGENTFIELD_AUTHORIZATION_ENABLED=true) plus /debug/pprof/*, and it's a no-op when unset. It is not general UI admin auth yet, but it's the hook your "keep only the admin token for the UI" idea would hang off.
• The connector API (AGENTFIELD_CONNECTOR_TOKEN + AGENTFIELD_CONNECTOR_CAP_* set to true/readonly/false) is the closest thing in the tree to what you're asking for: a separate token with per-capability enable and a real read-only mode enforced server-side. It's still a single token configured in YAML/env, and it only covers the /connector/* surface.
• Package-install and secret endpoints have an extra guard (PrivilegedAccess): with no API key configured they're loopback-only. Same key when one is configured, though.
• Opt-in DID request signing plus tag-based access policies give per-agent identity for agent→agent calls, but they layer on top of the global key rather than replacing it.

On rate limiting: #952 landed "per-key" limits, but that's not evidence multiple keys exist — and it doesn't actually key on the API key today; rateLimitKey() prefers an api_key_identity context value that nothing sets, so every limit falls back to per-IP. With a single global key that's arguably the right behavior for now; it becomes meaningful once real key identities exist.

Plan. Full virtual keys are a multi-week epic: a hashed key store + migration, a scope vocabulary (coarse groups like executions:write / logs:read / dag:read / packages:admin / secrets:admin — there are ~1000 route registrations, so per-route ACLs aren't realistic), scope guards on each route group, a key-management page in the UI with scope-aware nav, af keys create|ls|revoke, and docs. The legacy AGENTFIELD_API_KEY would stay as an implicit all-scopes key so existing deployments and SDK nodes don't break. The likely first slice is a read-only key (AGENTFIELD_API_READONLY_KEY → auth_level: read_only, rejected on writes) — with an explicit allowlist, since a few read endpoints are POST (/executions/batch-status, /executions/:id/logs, /nodes/status/bulk).

Keeping this open as the tracking issue for the epic. If you want a key that can only start runs and never read DAG/logs (rather than the inverse read-only key), say so — that ordering changes which scope lands first.

[pocesar]

@AbirAbbas the most important one is to be able to query an execution by id and return the execution details: input and result payload, status, id, and the metadata (notes, started, completed, updated, etc)

[AbirAbbas]

Your narrowed ask — one execution by id with input, result, status, notes and timestamps — is in v0.1.137:

POST /api/v1/agentic/query
{"resource": "executions", "filters": {"execution_id": "<id>"}}

returns just that execution with input, result, status, notes, session/actor and started/completed/created/updated timestamps (#1005 — the filter used to be ignored). GET /api/ui/v1/executions/{id}/details takes the same API key and adds sizes, retry_count and approval fields; it's in the API catalog and docs/api/EXECUTE.md points at it now.

The epic itself is still open and it's a design decision, so @santoshkumarradha: the first slice I'd ship is an env-configured read-only key — AGENTFIELD_API_READONLY_KEY, validated in the same middleware, auth_level: read_only, enforced with an explicit (method, path) allowlist rather than "reject non-GET" because several read endpoints are POST (agentic/query, executions/batch-status, nodes/status/bulk); the legacy key stays an implicit all-scopes key. Rate-limit identity (api_key_identity, which nothing sets today) should be wired at the same time so the two credentials get separate buckets — doing it earlier would collapse a multi-replica agent fleet into one per-key bucket, which is stricter than the per-IP behaviour you have now.

@pocesar — is read-only still the most useful first key for you, or would a start-runs-only key (can execute, can't read DAG/logs) unblock more?

[pocesar]

@AbirAbbas yes the read-only is still the most useful for my use case, but the start runs only is also interesting.