Auth: API key authentication for write endpoints and MCP

[DutchJaFO]

Context

Authentication has two distinct contexts that need different handling:

HA add-on via ingress — the HA supervisor authenticates all ingress traffic before it reaches the add-on. Only logged-in HA users can reach the add-on's ingress path. No additional auth is needed for the management UI when accessed this way.

Direct port / standalone Docker / MCP — requests arrive without any upstream authentication. Write endpoints and the MCP endpoint must require a valid API key.

Approach

A single API key, set by the user in configuration, protects all write endpoints and the MCP endpoint.

HA add-on

The key is set in the add-on's configuration panel (addon/config.yaml option api_key). The HA supervisor exposes it as an environment variable (Quotinator__ApiKey). No UI in the add-on itself for key management.

Standalone Docker

The same env var (Quotinator__ApiKey) is set directly, e.g. via docker run -e Quotinator__ApiKey=... or docker-compose.yml.

If no key is configured

The app starts but write endpoints and the MCP endpoint return 503 Service Unavailable with a message indicating auth is not configured. This prevents accidental open write access.

Implementation checklist

• Add api_key option to addon/config.yaml (optional string, no default)
• Add translations for the new option to addon/translations/en.yaml, nl.yaml, de.yaml
• Read Quotinator:ApiKey from config in Program.cs
• Implement ApiKeyAuthenticationHandler or middleware that checks Authorization: Bearer <key> on protected routes
• Apply auth requirement to all write endpoints (POST, PUT, DELETE on /api/v1/quotes) and /mcp
• Return 401 Unauthorized when the key is missing or wrong; 503 or startup warning when no key is configured at all
• Add IApiLocalizer message keys for auth error responses (with translations in all three locale files)
• Document the env var and HA config option in README.md and addon/DOCS.md

Notes

• Authorization: Bearer <key> is the standard mechanism; also consider X-Api-Key as a simpler alternative for consumers that struggle with Bearer headers
• Read endpoints remain unauthenticated — Quotinator's primary use case is serving quotes to display tools
• The management UI accessed via HA ingress relies on the supervisor's authentication; no Blazor-level auth guard is needed for ingress-only deployments

[DutchJaFO]

Addition: key management UX

The management UI (see #17) should include a key management page at /admin/settings (or /admin/auth) with the following:

• Current key status — show whether an API key is configured; display a masked version (e.g. ••••••••abc123) so the user can verify which key is active without exposing it fully
• Key generator — a "Generate key" button that produces a cryptographically strong random key (e.g. 32-byte base64url) and displays it in a copyable field; the user then pastes it into the HA add-on config panel or their docker-compose.yml
• Guidance copy — inline instructions explaining where to paste the key for each deployment variant (HA add-on config panel vs Docker env var)

The app does not write the key itself — that always goes through the HA config panel or Docker env. The UI is a generator and status display only.

This also means the Authorization: Bearer <key> header format used by the API should be shown in the UI so users can configure their API clients correctly.