Description

Add optional token-based authentication (API key) to the FastAPI REST API server. When the ADMIN_API_KEY environment variable is set, all endpoints (except / redirect, /docs, and /openapi.json) require a valid X-API-Key header. When unset, the server behaves as before with no auth.

This addresses the security concern that deployed instances accept requests from anyone without authentication.

Fixes #3311

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation update

How Has This Been Tested?

• Unit Test

Test suite: tests/test_server_auth.py — 73 tests

Tests run against the actual server/main.py app via FastAPI's TestClient (full ASGI round-trip).

TestAuthDisabled (22 tests)

• All 10 endpoints accessible without any API key
• Supplying a random key when auth is disabled still works
• Root / redirects to /docs
• Parametrized check: no endpoint returns 401

TestAuthEnabled (32 tests)

• Missing key → 401 with detail mentioning X-API-Key
• Wrong key → 401 with "Invalid" detail
• Empty string key → 401
• Near-miss key (off by one char) → 401
• Key with extra whitespace → 401
• Key prefix only → 401
• Different case key → 401
• WWW-Authenticate: ApiKey header present on 401 responses
• Parametrized: all 10 endpoints reject missing key
• Parametrized: all 10 endpoints reject wrong key
• Root / always accessible without key
• All 10 endpoints return non-401 with correct key, with full CRUD verification

TestAuthenticatedCRUDFlow (2 tests)

• Full create → read → search → update → history → delete cycle through auth, verifying each mock was called
• Same cycle without auth: all blocked at 401, verifying no mock was called (auth blocks before handler)

TestAuthEdgeCases (6 tests)

• 4096-character API key works
• Special ASCII characters in key work
• ADMIN_API_KEY env var completely absent → auth disabled
• Toggle auth on then off (simulated restart)
• /openapi.json and /docs accessible without key when auth enabled
• OpenAPI schema description mentions "Authentication"

TestStartupLogging (2 tests)

• Warning logged when ADMIN_API_KEY is not set
• Info logged when ADMIN_API_KEY is set

$ python -m pytest tests/test_server_auth.py -v
# 73 passed in 1.74s

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• I have checked my code and corrected any misspellings

Maintainer Checklist

• closes Add Authentication Token to FastAPI Server for Endpoint Security #3311
• Made sure Checks passed

🤖 Generated with Claude Code