feat(auth): verify machine tokens for admin read APIs

docs/admin-suggestions-api.md

@@ -1,12 +1,12 @@
 # Admin suggestions API
 
-The portal provides a read-only view of one Discord **forum channel**, using the existing NextAuth admin session and configured Keycloak role. Player sessions and Discord bot credentials are not accepted as API credentials. Sign in at `/admin/login` first; same-origin browser calls send the session cookie. Unattended machine authentication is not provided.
+The portal provides a read-only view of one Discord **forum channel**, using the existing NextAuth admin session or a verified Keycloak machine bearer token. Player sessions and Discord bot credentials are not accepted as API credentials. Browser users sign in at `/admin/login`; same-origin calls send the session cookie. Machine clients use `Authorization: Bearer <access-token>` with the configured portal audience and **client** role. See [Admin API authentication](admin-api-authentication.md) for verification rules, safe identity checks, and failure behavior.
 
 ## Portal interface
 
 Open `/admin/suggestions` from the administrator navigation. The idea desk lists active or archived forum posts with tags, status, approximate message counts, author IDs, timestamps, and Discord links. Select a title to open `/admin/suggestions/:id`, read the starter post and its reaction counts, and page through discussion newest-first. The starter is not duplicated in the discussion view.
 
-The UI uses these same session-protected GET endpoints, not a second integration. Both pages independently check admin access before rendering; the APIs recheck it on every read. Expired/unauthorized API access offers an admin sign-in link. Loading, empty/deleted content, missing-text, and retryable failure states are explicit. Changing status aborts obsolete requests, and pagination restores keyboard focus to the page indicator. Text is rendered literally with React escaping, never as HTML or interpreted Discord Markdown. No bot token, forum configuration value, reply input, vote button, or moderation control is added to the client bundle.
+The UI uses these same admin-protected GET endpoints with its browser session, not a second integration. Both pages independently check admin access before rendering; the APIs recheck it on every read. Expired/unauthorized API access offers an admin sign-in link. Loading, empty/deleted content, missing-text, and retryable failure states are explicit. Changing status aborts obsolete requests, and pagination restores keyboard focus to the page indicator. Text is rendered literally with React escaping, never as HTML or interpreted Discord Markdown. No bot token, forum configuration value, reply input, vote button, or moderation control is added to the client bundle.
 
 Pagination history is page-local and resets when switching status or leaving the page. Reload the browser to refresh a view; upstream reads may use the documented 30-second cache. The real forum ID is still configured only through GitOps, not the UI or source.
 
@@ -37,8 +37,9 @@ Suggestion fields: `id`, `title`, `authorId`, `createdAt`, `archived`, `locked`,
 
 Errors use RFC 9457 `application/problem+json`, HTTP-matching `status`, stable `urn:error:*` types, and safe details:
 
-- `401 unauthorized`: no admin session; no redirect.
-- `403 forbidden`: session lacks the required role.
+- `401 unauthorized`: no admin session or invalid supplied credentials; no redirect; includes `WWW-Authenticate: Bearer realm="admin-api"`.
+- `403 forbidden`: verified identity lacks the required role (configured-client role for bearer tokens).
+- `503 admin-auth-unavailable`: authentication configuration, browser session service, or JWKS service unavailable; no session fallback for supplied credentials.
 - `400 invalid-request`: invalid ID, cursor, limit, status, or list/message query parameter.
 - `404 suggestion-not-found`: inaccessible/deleted thread, or thread outside the configured forum.
 - `405 method-not-allowed`: writes are unsupported; `Allow: GET, HEAD`.