docs(openapi): OpenAPI 3.1 management spec (SSOT) + README #2056

Merged

devops-engineer merged 2 commits from feat/openapi-management-spec into main 2026-06-01 16:09:01 +00:00

Conversation 11 Commits 2 Files Changed 2

+2109

2 Commits

Author	SHA1	Message	Date
core-be	8cea4a30c4	docs(openapi): apply Five-Axis review fixes to management spec ... Verified each against the authoritative handler source (molecule-core workspace-server + molecule-controlplane) before editing: 1. tenantAdminToken: http/bearer -> apiKey header X-Molecule-Admin-Token. authenticateTenant (controlplane workspace_provision.go) reads that header, NOT Authorization, and derives org from the token (SELECT org_id ... WHERE admin_token=$1). Removed orgRoutingHeaderId from the DELETE /api/v1/workspaces/{workspace_id} security — no X-Molecule-Org-Id is read on deprovision. 2. ProvisionStatus.stage: added `failed` (emitted by orgs.go on failed/deprovisioning/deprovisioned). Existing launching/installing/ starting/configuring_https/ready all confirmed emitted by orgs_progress.go + estimateBootProgress — none trimmed. 3. GET /workspaces/{id}: set security: [] — router.go registers it outside every auth group (intentionally open for canvas-node self- polling). Dropped the now-inapplicable 401. 4. Multi-period budget shape: added `budget_limits` (canonical) + legacy `budget_limit` to PatchBudgetRequest, and `periods` (+ PeriodBudget) to BudgetResponse, matching budget.go budgetResponse/PatchBudget. 5. GET tenant llm-billing-mode already modeled (handler serves GET+PUT) — no change needed; verified. 6. Added prune=true destructive note (only literal "true" permanently deletes, internal#734) and the CP-admin /api/v1/admin/workspaces/{id}/llm-billing-mode GET+PUT pair (cpAdminBearer, requires ?org_slug=). redocly lint clean under both recommended and recommended-strict. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-05-31 22:29:07 -07:00
core-be	dc7e660e90	docs(openapi): add OpenAPI 3.1 management spec (SSOT) + README ... Author workspace-server/docs/openapi/management.yaml — the hand-authored, authoritative OpenAPI 3.1 contract for the Molecule platform MANAGEMENT surface, spanning both services in one spec: - CP (api.moleculesai.app, /api/v1/*): orgs create/get/list/delete/export/ provision-status, public instance lookup, billing (invoices/checkout/ portal/topup), admin (admin-create-org w/ dry_run, tenant delete + scrub w/ confirm guard, diagnostics, redeploy + fleet, workspace env w/ force guard, ListOrgWorkspaces, admin-token, thin-ami + runtime-image pins), provisioning (provision w/ 422 RUNTIME_PIN_MISSING, deprovision, status). - Tenant workspace-server: /workspaces[/:id] CRUD + restart/pause/resume, budget, llm-billing-mode, /workspaces/:id/secrets, /settings/secrets, /org/import, /org/templates, /org/tokens (Org API Key mint/revoke), /templates[/import], /bundles export/import. Defines the five security tiers as securitySchemes (workosSession cookie, cpAdminBearer, provisionSecret [+ tenantAdminToken on deprovision], orgApiKey + org routing header, workspaceToken) and applies the correct scheme(s) per-route. Dry-run / confirm / force guards modelled per-operation. Grounded in the router + handler sources (controlplane + workspace-server), not just the synthesis doc — notably llm-billing-mode is modelled on the real tenant route (/admin/workspaces/:id/llm-billing-mode, AdminAuth), with the divergence from the synthesis doc noted in the README. Adds README.md documenting the two-service split + the security-scheme→ surface tier matrix. This is the SSOT the management MCP + CLI + docs derive from (PLATFORM-MANAGEMENT-API.md §5c / RFC #1706). Supersedes the swaggo /schedules stub for the management surface; runtime surface stays out of scope. Per dev-sop Phase 1-4 + Five-Axis self-review (in PR body). Lints clean: npx @redocly/cli lint management.yaml (0 errors, 0 warnings). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-05-31 20:40:36 -07:00