API Reference

Two separate REST surfaces:

Data plane (/v1/..., /healthz) — event ingestion and read, for end users and apps/publishers.
Admin API (/admin/v1/...) — platform-operator/tenant-admin registry, config, and PII-gated read surfaces.

Conventions that hold across both

Auth: Authorization: Bearer <JWT>, never cookies (see Authentication). Missing/invalid token → 401.
Tenant scope: always derived from the token; never a client-supplied field, path segment, or query parameter (the tenant-registry resource itself is the one exception — see Tenants).
Content type: request and response bodies are application/json, except GET /v1/stream's text/event-stream frames.
Error bodies: most error responses are plain text (http.Error), not a JSON envelope — don't assume {"error": "..."} unless a specific route below says otherwise.
DELETE/revoke routes return 204 No Content on success.

Method	Path	Plane	Auth
`GET`	`/healthz`	—	none
`POST`	`/v1/events`	Data	end-user SSO-JWT or app service-JWT
`GET`	`/v1/feed`	Data	end-user SSO-JWT
`GET`	`/v1/stream`	Data	end-user SSO-JWT
`POST`	`/v1/render-tokens/verify`	Data	end-user SSO-JWT
`GET`	`/admin/v1/me`	Admin	any authenticated SSO-JWT (no role minimum)
`GET`/`POST`/`PATCH`/`DELETE`	`/admin/v1/tenants...`	Admin	`platform-operator`
`GET`/`POST`/`PATCH`/`DELETE`	`/admin/v1/apps...`	Admin	`tenant-admin`
`GET`/`POST`/`PUT`/`DELETE`	`/admin/v1/policies...`	Admin	`tenant-admin`
`GET`/`POST`/`PUT`/`DELETE`	`/admin/v1/event-catalog...`	Admin	`tenant-admin`
`GET`/`POST`	`/admin/v1/notifications...`	Admin	`tenant-admin` (feed inspector: explicit `tenant-admin`)
`GET`/`POST`/`DELETE`	`/admin/v1/rbac/...`	Admin	`tenant-admin` (granting `platform-operator` requires already holding it)
`GET`	`/admin/v1/profile`, `/admin/v1/analytics/summary`	Admin	`tenant-admin`
`GET`	`/admin/v1/activity`, `/admin/v1/audit`	Admin	explicit `tenant-admin`

"Explicit tenant-admin" means platform-operator alone is not sufficient — see Authz planes → The PII gate.