docs: 19 endpoints missing RBAC role tables in api-reference.md

[OneStepAt4time]

API Documentation Audit — Findings

Per Athena's request, I audited every route in src/routes/ against docs/api-reference.md. Results:

Summary

• 108 endpoints in source code
• 34 endpoints have RBAC role tables in docs
• 19 endpoints have requireRole() in source but no role table in docs
• 0 role mismatches (where both exist, they agree)
• 0 undocumented routes (all routes are documented)

Missing RBAC Role Tables

These endpoints enforce roles via requireRole() but the docs don't show the required roles:

Auth endpoints (admin-only):

• DELETE /v1/auth/keys/:id — admin
• GET /v1/auth/keys — admin
• GET /v1/auth/keys/:id/quotas — admin
• PATCH /v1/auth/keys/:id — admin
• POST /v1/auth/keys — admin
• POST /v1/auth/keys/rotate — admin
• POST /v1/auth/keys/:id/rotate — admin
• PUT /v1/auth/keys/:id/quotas — admin

Legacy aliases (same as /v1/auth/keys):

• DELETE /v1/keys/:id — admin
• GET /v1/keys — admin
• POST /v1/keys — admin

Health & diagnostics:

• GET /v1/health — admin
• GET /metrics — admin

Session endpoints:

• GET /sessions — admin, operator, viewer
• GET /v1/sessions/:id — admin, operator, viewer
• GET /v1/sessions/:id/tools — admin, operator, viewer

Monitoring & usage:

• GET /v1/audit — admin
• GET /v1/usage/by-key — admin
• POST /v1/handshake — admin, operator, viewer

Recommendation

Add | Role | Required | tables to each of these 19 endpoint sections in api-reference.md. This is a doc-only change — no code changes needed.

Scope

• docs only
• no Phase 4 gate
• estimated effort: ~30 min (adding role tables to existing endpoint sections)

Assignee

Scribe

[aegis-gh-agent]

Resolved by PR #3319 (merged on 2026-05-14). Squash merged as 7eb9baa — 14 RBAC role tables added, handshake marked unauthenticated, /sessions/:id/tools documented as ownership-based.