GUI Backend API

Base URL:

http://<host>:<port>

Versioned API prefix:

/api/v1/

Public endpoints (no auth)

Method	Path	Description
GET	/healthz	Liveness probe
GET	/api/v1/config	Public server config (stale_threshold_seconds)

Auth endpoints

Method	Path	Description
POST	/api/v1/auth/token	Dev-mode token exchange (404 when dev mode disabled)
GET	/api/v1/auth/me	Returns authenticated user + role

Fleet / node / telemetry endpoints

Method	Path	Required permission
GET	/api/v1/fleet	fleet:read
GET	/api/v1/fleet/nodes	fleet:read
GET	/api/v1/fleet/summary	fleet:read
GET	/api/v1/node/{id}	fleet:read
GET	/api/v1/node/{id}/activation-timeline	activation:read
GET	/api/v1/node/{id}/fingerprints	lock:read
GET	/api/v1/node/{id}/policy-results	policy_eval:read
GET	/api/v1/telemetry	telemetry:read
GET	/api/v1/events	telemetry:read
GET	/api/v1/locks/{node_id}	lock:read

Release endpoints

Method	Path	Required permission
GET	/api/v1/releases/latest	release_channel:read
GET	/api/v1/releases	release_channel:read
GET	/api/v1/releases/{channel}	release_channel:read

Tooling endpoints (compute-and-return)

Method	Path	Required permission
POST	/api/v1/tooling/build-bundle	bundle:build
POST	/api/v1/tooling/simulate-policy	simulation:run

These endpoints are designed as compute-and-return operations, not persistence operations.

Error and versioning behavior

• Requests to legacy /api/* paths (outside /api/v1/*) return 410 Gone for authenticated callers.

• Unauthenticated requests to protected API paths return 401.

• Permission mismatch returns 403.

• Mutating methods on read-only API surfaces are rejected with 405.

Example requests

curl -sS http://127.0.0.1:8090/healthz
curl -sS http://127.0.0.1:8090/api/v1/config

TOKEN="$(curl -sS -X POST http://127.0.0.1:8090/api/v1/auth/token \
  -H 'Content-Type: application/json' -d '{"role":"auditor"}' \
  | python3 -c 'import json,sys;print(json.load(sys.stdin)[\"token\"])')"
curl -sS http://127.0.0.1:8090/api/v1/fleet -H "Authorization: Bearer $TOKEN"

curl -i http://127.0.0.1:8090/api/fleet -H "Authorization: Bearer $TOKEN"

Not implemented / no evidence

• WebSocket API endpoints: not implemented in GUI backend route registration.

• /metrics endpoint on GUI server: not implemented; explicitly blocked.

Evidence

• gui/internal/api/gateway.go (NewGateway)

• gui/internal/api/enforce.go (EnforceReadOnly, BlockAdminPaths, security middleware)

• gui/internal/auth/middleware.go

• gui/internal/auth/rbac.go

• gui/internal/api/versioning_test.go

• gui/internal/api/tooling_test.go

• gui/internal/api/config_test.go

• docs/_generated/test-outputs/gui-startup.txt