feat(ingest): let a scoped ingest key authenticate /v1/* and /api/v1/*, so an agent off-box can be observed

[vivekchand]

Problem

An agent is observable by ClawMetry only if the daemon runs on the same machine as the agent. That excludes CI runners, containers, serverless, hosted agent products, and a teammate's laptop — i.e. most agents that cost real money.

Verified in tree:

• dashboard.py::_check_auth gates /v1/* on OPENCLAW_GATEWAY_TOKEN; loopback is trusted, and the only escape hatch is CLAWMETRY_OTLP_ALLOW_UNAUTH=1 (a LAN-wide open door, not a credential).
• docs/CUSTOM_RUNTIME_INGEST.md: the write API authenticates on one static CLAWMETRY_INGEST_TOKEN shared by the whole install — no rotation, no revocation, no attribution.
• clawmetry/endpoints.py: ingest.clawmetry.com accepts E2E-sealed snapshots from an authenticated daemon and nothing else, so there is no key a remote agent could hold.

Competitive context: Bronto's entire agent story is one public OTLP endpoint plus x-bronto-api-key. That is why they can publish an OpenClaw integration page and we cannot publish a CI one.

What already works — do not rebuild it

• dashboard.py::_otlp_decode already handles protobuf, OTLP/JSON and gzip, keyed off Content-Type / Content-Encoding. Wire coverage is at parity with Bronto today; it is simply undocumented and loopback-scoped.
• _process_otlp_traces already recognises gen_ai.operation.name and slugs a foreign service.name into its own runtime rather than mis-bucketing it as openclaw.
• PR feat: build your own UI, a keyed and scoped read API over the q/1 contract #5676 ships clawmetry/apikeys.py: cmk_<id>_<secret>, sha256 at rest in ~/.clawmetry/api_keys.json (0600), create / verify / revoke / list_keys / scope_catalogue, and the clawmetry key CLI.

This issue is the write half of #5676, not a parallel key system.

Scope

1. A write scope. Add write:ingest to apikeys.SCOPES. Careful: scope_catalogue() derives methods from query_contract.live_methods_by_scope, which is read-only by construction. A write scope maps to no q/1 shape, so the catalogue needs a branch that says so rather than rendering an empty method list that reads like a bug.
2. Key auth as an additional path. Accept x-clawmetry-key on /v1/logs, /v1/metrics, /v1/traces and /api/v1/runs*. Loopback and the gateway token keep working unchanged — this adds a door, it does not move the existing one.
3. No CORS, POST only. Ingest is server-to-server. Do not extend routes/public_api.py::_add_cors; it is deliberately pinned to /api/q/. A browser-resident ingest key is not a use case, and making it one re-opens the hole feat: build your own UI, a keyed and scoped read API over the q/1 contract #5676 closed.
4. Routing headers, resolved once per request and stamped on every event in it:
   • x-clawmetry-runtime — validated against entitlements.ALL_RUNTIMES, with an explicit free-form fallback for custom engines (the write API already accepts arbitrary runtime strings).
   • x-clawmetry-env — environment/project string, [a-z0-9_-]{1,64}. This is the one grouping axis above runtime; resist growing it into Bronto's dataset/collection/tags taxonomy.
5. Documented limits and honest failures. Return, don't 500: 200 accepted, 400 malformed, 401 bad/absent key, 403 key lacks write:ingest, 413 over size, 429 over rate. Caps to publish: 10 MB body, 1000 events per batch (already the custom-runtime cap).
6. CLI: clawmetry key create --scope write:ingest prints a curl that actually works against the local dashboard.

Non-goals

Regional endpoint split (Bronto's own troubleshooting page shows region-scoped keys are their most common support failure). Per-key rate limiting — that belongs on the hosted side. A base "any format" endpoint. CORS.

Traps

• _check_auth returns early for /api/q/ precisely so the stricter gate in routes/public_api.py is the only gate. Do the same here — one gate, in the ingest module — rather than layering a second check on top of the gateway-token check.
• Pushed events must go through local_store.ingest, so secret redaction and dedupe apply to foreign data exactly as they do to detected data. Do not add a bypass for speed.
• A new OSS route with no cloud_route_policy entry is a SystemExit in apply_policy and cloud will not boot. Land the cloud-side policy classification in the same window (see the paired cloud issue).

Acceptance

• An agent running in a GitHub Actions container, with no ClawMetry daemon anywhere on the machine, pushes OTLP with a key and appears as a live session with correct token cost.
• Revoking the key stops ingest within one request.
• Loopback with no key behaves exactly as it does today — regression test, not manual check.
• A read:metrics key gets 403 on ingest; a write:ingest key gets 403 on /api/q/1/*. Both pinned by test.
• x-clawmetry-env is filterable in at least one tab, or the header is not shipped.

Depends on #5676.

Part of the ingest-gap plan (phase 1, item 1 of 5).

[vivekchand]

Phase 1 issue map — "open the front door"

The gap this closes: an agent is observable only if the daemon runs on the same machine as the agent. These eight issues, in dependency order:

#	Repo	Issue
1	clawmetry	#5679 — scoped ingest key authenticates /v1/* and /api/v1/*
2	clawmetry-cloud	#2344 — name the two trust classes (gates #2343)
3	clawmetry-cloud	#2343 — hosted ingest key + OTLP endpoint
4	clawmetry-pro	#230 — pushed telemetry becomes real sessions; honest control verdicts
5	clawmetry	#5682 — generated docs/INGEST.md + drift test
6	clawmetry	#5681 — per-runtime setup prompts
7	clawmetry	#5680 — "Send your data" onboarding step + live status strip
8	clawmetry-landing	#754 — public endpoint reference; reconcile reach + storage claims

Upstream dependency: clawmetry PR #5676 ships clawmetry/apikeys.py (cmk_ scoped keys, clawmetry key CLI). #5679 extends it with a write scope rather than starting a second key system.

Ordering that matters: #2344 lands before #2343 (a plaintext trust class named before it exists, not after it becomes a P0), and #5682 lands before #754 (the landing page is written from the generated doc, because drift-bot greps repo docs and fails claims the repo denies).

Deliberately out of scope for phase 1 — and mostly out of scope permanently: the 33 AWS / 11 Azure / 17 infra integration pages, generic log parsing (syslog/CEF/GELF), an LLM-authored parser, a search language and dashboard builder, and being a destination for Fluent Bit / Vector / Logstash / the Datadog Agent. Those make ClawMetry a worse log platform and a less distinctive agent platform.

[vivekchand]

Checked origin/main (4c192fe6, fetched 2026-09-12): clawmetry/apikeys.py does not exist, and there's no write:ingest scope or x-clawmetry-key handling anywhere in dashboard.py or routes/.

This is fully covered by open PR #5684 (feat/ingest-key, stacked on open PR #5676 feat/build-your-own-ui). PR #5684's body says "Closes #5679, #5682, #5681, #5680" and its commit 1, titled "The ingest key (#5679)", implements this issue's ask point-for-point:

• clawmetry key create --scope write:ingest, same cmk_ key shape/store as feat: build your own UI, a keyed and scoped read API over the q/1 contract #5676's read keys (not a second key system, as this issue asked).
• x-clawmetry-key accepted on the OTLP ingest surface, with routing headers x-clawmetry-runtime (validated against entitlements.ALL_RUNTIMES, free-form fallback) and x-clawmetry-env, written into resource attributes the mappers already read — matching this issue's scope items 4.
• No CORS added to ingest, POST only — matching the "No CORS, POST only" requirement.
• One gate (_check_auth steps aside for a keyed request, same pattern as /api/q/) rather than a second layered check — the exact trap this issue calls out.
• PR body explicitly claims the acceptance-criteria bug this issue's own author would care about: a write-only key got 403 from /api/q/1 after a live-run bug was found and fixed ("verify() accepts it since it is a valid key, and nothing asked whether it held any read scope. Now 403, pinned by a test") — directly satisfies this issue's "A read:metrics key gets 403 on ingest; a write:ingest key gets 403 on /api/q/1/*. Both pinned by test" acceptance item.
• 25 guards in tests/test_ingest_key.py per the PR body, registered in ci.yml.

Not merged (PR base is feat/build-your-own-ui, not main; mergeable_state: unknown). Per the task guidance I'm not merging/closing — leaving this open until #5676 merges, then #5684.

---

Generated by Claude Code