Request flows

Ingest (agent → API → TSDB)

1. The agent opens an mTLS conn to :8443
2. The server TLS config verifies the peer cert against the issued CA
3. agentIDFromCert(r) → identity (NEVER from the body/header)
4. SELECT organization_id, status, region_id FROM agents
5. Sample[]: organization_id + agent_id + host are attached to every metric
6. router.VMForRegion(region_id) → the region's TSDB client
7. vm.Write(samples)
8. UPDATE agents SET last_seen_at = now()

Cabinet query

1. Browser → /api/v1/orgs/:slug/query/range?metric=X&host=Y
2. Session middleware (cookie) → userCtx
3. orgMiddleware → orgContext{OrgID, UserID, Role}
4. composeQuery("X", {organization_id: OrgID, host: Y})
5. vm.Range(promQuery, start, end, step)

Embed query

1. Partner backend: POST /api/v1/embed/tokens with mk_xxx
2. The API verifies the key origin against the allowlist
3. A JWT is issued: claims contain {org_id, filters}
4. The partner puts the JWT in an iframe or postMessage
5. SDK → /api/v1/embed/query/range with a Bearer JWT
6. embed.Required: parses the JWT, extracts filters from claims
7. composeQuery with claim.filters