Management API

The management API is a Python FastAPI service. Established tenant-management routes and mounted-but-provisional operator read contracts share one process. A mounted route is not production operator readiness.

Base URL and contract artifacts

Local default: http://127.0.0.1:8010.

• GET /openapi.json, /docs, /redoc
• GET /health, /ready, /metrics
• GET /v1/tenant/ping — authenticated tenant smoke route

The mounted route inventory is generated from the FastAPI app and checked in under services/api/scripts/route_inventory.json. The OpenAPI snapshot is checked separately. Both must be regenerated when a route or schema changes.

services/api/.venv/bin/python services/api/scripts/route_inventory.py --check
bash .github/scripts/check-openapi-snapshot.sh

Two authentication modes

A browser bearer token is not an alternative operator-session design. Operator session issuance is default-off and requires the auth/session feature path; the development HS256 stub is not a production issuer. See Operator sessions.

Route families

The D2 list uses an opaque, signed cursor and a bounded time range; invalid or expired cursors are VALIDATION_ERROR, not a silent restart. A trace lookup that is unknown or outside the tenant returns NOT_FOUND.

Authorization sequence

1. Authenticate the credential (PAT bearer or operator session).
2. For a path-scoped route, compare the path org_id with the verified organization.
3. Check the required permission bit or role.
4. Open a tenant-scoped database session and set app.current_org_id for the transaction.
5. Apply explicit org_id predicates even where RLS is enabled.
6. Map missing or cross-tenant resources to 404 where existence leakage is a risk.

A path mismatch is not permission to use the path organization. The token's organization wins, and the request is rejected.

Example: list token metadata

curl -s \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  "http://127.0.0.1:8010/v1/tokens"

A token response returns metadata such as ID, name, type, permissions, and timestamps. It never returns the plaintext secret after creation. Do not put the token in a URL.

Error behavior

The shared error envelope is defined by the API error package; do not return ad-hoc JSON. A 202 deletion response is an accepted request, not a completed purge.

Operator D1/D2 boundary

D1/D2 are read-only and return Cache-Control: no-store. D2 exposes approved run metadata only: no prompts, completions, hidden reasoning, raw tool arguments, or unredacted payloads. The Console must not fabricate a detail when the upstream returns unavailable.

The API has no general provenance inspector, replay action, export endpoint, or operator write tool in this slice. Mounted presentation in the Console is not an owning contract.

Configuration

Operator session feature flags and TOTP settings belong to the auth/API session path; do not infer them from a Console environment variable.

Readiness boundary

Production promotion still requires AuthService/session/MFA integration, deployment-origin and CORS/CSRF evidence, two-tenant negative tests, redaction and hostile-content tests, performance/availability evidence, and rollback/incident runbooks. The full management product and provenance inspector are not complete until those gates are accepted.

Related

• Operator sessions — cookie and step-up contract
• Responses — data-plane response shapes
• Data lifecycle and deletion — 202, receipts, and holds
• Billing and budgets — rate cards and reservation limits
• Console — how the read slices are presented
• Tenant isolation — path mismatch and 404 rules