Skip to main content

API Surfaces and Authentication

Created: 2025-08-06 Updated: 2026-10-11

Supervaizer exposes FastAPI's generated documentation plus four route surfaces with different access rules.

Route Surfaces​

SurfaceAccess rule
/, /.well-known/*, /docs, /redoc, /openapi.jsonPublic, no authentication
/api/* (for example /api/supervaizer/..., /api/agents/{slug}/...)X-API-Key header required; 401 when missing or wrong. Mounted only when Studio credentials are configured or local mode is on
POST /a2a, GET /a2a/eventsX-API-Key with write scope for /a2a, read scope for /a2a/events; 403 when the scope is insufficient
/manage/* (admin UI and workbench)Tailscale client IP only, no API key. See 2025_08_ADMIN_README.md

Workflow index: product/feature-map.md.

Data resources​

DataResource callbacks are mounted at /api/agents/{slug}/data/{name}/ (list, detail, create, update, delete, and import/). They sit on the /api router, so they need X-API-Key; writes also need write scope. They are not under /api/supervaizer. A workspace authorization token is required on every call, including local mode. A route is registered only when that callback is set. See product/feature-map.md.

API Key​

  • SUPERVAIZER_API_KEY registers a write-scope key at import time. write implies read.
  • Outside local mode, if the variable is unset a key is generated at startup and only its fingerprint is logged. Set SUPERVAIZER_API_KEY explicitly if you need to call /api or /a2a yourself.
  • Local mode (supervaizer start --local) uses the key local-dev.
  • Denied requests are logged at WARNING with IP, path, reason, and a truncated key preview, never the raw key.

Interactive Documentation​

InterfaceURLNotes
Swagger UIhttp://localhost:8000/docsTry requests in the browser
ReDochttp://localhost:8000/redocRead-only reference
OpenAPI schemahttp://localhost:8000/openapi.jsonOpenAPI 3.1, machine readable

The schema declares no security scheme, so Swagger shows no Authorize button. To call a protected route from Swagger, open the operation, click Try it out, and fill the X-API-Key header field.

Committed OpenAPI Spec​

docs/api/openapi.json is generated by just generate-docs from src/supervaizer/examples/controller_template. Agent-specific routes in it belong to that example; your controller's spec lives at /openapi.json on the running server.

Uploaded on 2026-11-06 15:07:19