Skip to main content

Authenticated Swagger UI

OP-070 exposes FastAPI's built-in API documentation as an authenticated console capability.

What Changed​

  • Added protected docs routes:
    • /api/docs
    • /api/redoc
    • /api/openapi.json
  • Disabled the default public FastAPI docs routes.
  • Redirect unauthenticated docs requests to /login.
  • Reuse the OP-068 oneprotect_access_token httpOnly cookie as a same-origin bearer equivalent for API docs and Swagger "try it out" requests.
  • Polished OpenAPI metadata with title, description, same-origin server URL, and role-aware tag descriptions.
  • Group runtime operations under:
    • platform-admin
    • tenant-admin
    • operator
    • auditor
    • public
  • Add Required role: ... descriptions to generated operations.
  • Added an authenticated console link to "API Documentation".

Security Boundaries​

  • The browser cannot read the access token because the cookie remains httpOnly.
  • Backend token verification remains authoritative. Docs access does not create a new auth path or weaken OIDC/dev-token validation.
  • Swagger "try it out" works by sending the same-origin cookie back to the API; JavaScript does not copy tokens into local storage or visible page state.
  • Public unauthenticated API documentation is not exposed.

Validation​

  • tests/test_authenticated_swagger_ui.py
  • frontend/src/test/oneprotect-ui.test.tsx
  • Runtime OpenAPI metadata generated by FastAPI
  • Static contract metadata in specs/openapi.yaml

Non-Scope​

  • No new business APIs.
  • No SDK generation.
  • No external developer portal.
  • No separate Swagger pod or sidecar.