The REST API is served by greenkube-api under /api/v1 (and /api/v2 for changes, the ledger and recommendations v2). Interactive documentation and the OpenAPI schema are available at /api/v1/docs and /api/v1/openapi.json. The full reference is docs/api.md.
Machines send a scoped API key: Authorization: Bearer gk_<id>_<secret>. Administrators create keys in Settings > API keys or with POST /api/v1/auth/api-keys; the key is shown once. Scopes: read, write, approve, plans:deliver, signals:write, signals:report, metrics:read, admin. A request outside its scopes answers 403 INSUFFICIENT_SCOPE.
The dashboard signs in with POST /api/v1/auth/login and uses an HttpOnly session cookie. Mutations authenticated by the cookie need a same-origin Origin and the X-CSRF-Token header returned by GET /api/v1/auth/me.
Headless installs (config.apiAuthMode: api_key) have no accounts: the sign-in page posts an API key to POST /api/v1/auth/api-key-login ({"key": "...", "remember": false}), which checks it like a Bearer key and answers with a signed HttpOnly cookie, never the key itself. It accepts the bootstrap key or a scoped key with the read scope, needs HTTPS (or localhost), and lasts 12 hours (30 days with “Keep me signed in”). Revoking the key signs its browsers out.
Single sign-on works through an authentication proxy or native OpenID Connect, with IdP groups mapped to the viewer, operator and admin roles.
Unauthenticated requests answer 401. A production instance never serves anonymous requests.
POST /api/v1/sources/polaris/reports answers 404 for every key; nothing is stored. Footprint, recommendation and dashboard series are no longer exported on /prometheus/metrics: read them from /report/summary, /report/export, /metrics/summary, /metrics/dashboard-summary, /nodes and /recommendations instead (Upgrading).