Relationships
#2626 Docs: health endpoints need a valid token, not admin, and the stream ends on token revoke
Opened by stack72 · 9/28/2026
What changes (swamp-club#2504)
The fix for swamp-club#2504 changes two things the manual describes:
- GET /api/v1/health and GET /api/v1/health/stream accept any valid server token. They no longer require admin on access:*. Cluster instances, serve config, internal runs and the cancel routes stay admin-only.
- The SSE health stream is now a token session. When its token is revoked, rotated or expires, or its principal loses access, serve sends a final event named session-ended (data holds code and reason) and closes the stream. Each close records an auth.session.terminated audit event, the same as for WebSocket sessions. Revokes outside the instance take effect at the next revalidation pass, up to 30 s plus the datastore poll interval.
Pages to update
- content/manual/how-to/swamp-serve/monitor-server-health.md: drop the step that grants admin on access:* to the monitoring principal; a minted token is enough. Mention that the stream ends with session-ended when the token is revoked, rotated or expires.
- content/manual/reference/swamp-serve/rest-api.md: change the auth requirement for the two health endpoints from admin to a valid token, and document the session-ended event under the stream endpoint (existing consumers that ignore unknown event names are unaffected).
Land this after the swamp-club#2504 fix ships.
Closed
No activity in this phase yet.
stack72 commented 9/29/2026, 11:34:01 PM
Docs fix in swamp-club PR 1265 (one PR covering #2626, #2653, #2661, #2679, #2692, #2694, #2701, #2728, #2733, #2740). Note: auth.session.terminated is only recorded for token revoke/rotate/expire/delete closes, not access-removed or access-changed closes.
stack72 commented 9/29/2026, 11:35:31 PM
Documented in swamp-club PR 1265. rest-api.md: the health endpoints accept any valid token; the other endpoints remain admin-only, with 403 rows added; the session-ended event is documented with its close codes (4002, 4003, 4004) and the 30s + poll interval for revokes on other instances. The audit note says auth.session.terminated is recorded for closes caused by a token being revoked, rotated, expired or deleted, which matches the source. monitor-server-health.md drops the admin grant step, explains the narrowed snapshot, shows the session-ended event, and uses an admin token for /internal/runs.
Sign in to post a ripple.