molecule-core/workspace-server/docs/openapi/README.md

Molecule Platform OpenAPI specs

This directory holds the machine-readable API contracts for the Molecule platform.

File	Spec	Scope	Status
management.yaml	OpenAPI 3.1	The management surface across both services (orgs, billing, admin, provisioning, workspaces, secrets, templates, org-tokens, bundles).	SSOT — hand-authored.
swagger.yaml / swagger.json	OpenAPI 2.0	swaggo-generated stub, /schedules only (the per-workspace runtime surface).	Legacy stub; superseded for management by management.yaml.

management.yaml is the single source of truth the management tooling derives from — the management MCP server, the management CLI (molecule-cli), and the human-facing API docs (RFC #1706, the gap closed by PLATFORM-MANAGEMENT-API.md §5c). Do not hand-edit those clients' route maps; change them here and regenerate/derive.

The two-service split

One structural fact drives the whole spec: there are two services with two auth stacks, and the management surface spans both.

                         ┌─────────────────────────────────────────┐
   browser / CLI / MCP   │  Control plane (CP)                      │
        │                │  molecule-controlplane @ api.moleculesai │
        │  session       │  /api/v1/* (stable) [+ /cp/* sunset]      │
        ├───────────────▶│  orgs · members · billing · provisioning │
        │  admin bearer  │  · fleet/admin ops · pins                 │
        │  provision sec │                                          │
        └────────────────┴──────────────┬───────────────────────────┘
                                         │ edge reverse-proxy
                                         │ (subdomain / X-Molecule-Org-Slug)
                                         ▼
                         ┌─────────────────────────────────────────┐
   Org API Key / ws tok  │  Tenant workspace-server                 │
        │                │  molecule-core/workspace-server          │
        └───────────────▶│  ONE EC2 per org @ <slug>.moleculesai.app│
                         │  workspaces · secrets · templates ·      │
                         │  org-tokens · bundles                    │
                         └─────────────────────────────────────────┘

• Control plane (CP) — api.moleculesai.app, routes modelled under /api/v1/* (the /cp/* mirror is identical but sunset-headed per RFC #61 and is not duplicated in the spec). Owns orgs, members, billing, provisioning, fleet/admin ops.
• Tenant workspace-server — one EC2 per org at <slug>.moleculesai.app. Owns workspaces, agents, secrets, templates, org-tokens, bundles. Requests may also be sent to the CP host with an X-Molecule-Org-Slug header; the CP edge reverse-proxies them to the tenant host (the Authorization, X-Molecule-Org-*, and cookie headers pass through unchanged and the tenant's own middleware validates them).

The key consequence, called out in PLATFORM-MANAGEMENT-API.md: the Org API Key is a TENANT credential, not a CP one. It is full tenant-admin over its own org's workspace-server surface and reaches nothing on the CP (org create/delete, billing, members, provisioning all 401/403 it). That is why member/billing tools belong in a separate CP-admin MCP, not the org-key-authed management MCP.

Security scheme → surface map (the tier matrix)

management.yaml defines these securitySchemes; each operation declares the one(s) it accepts. Mirror of PLATFORM-MANAGEMENT-API.md §1:

Scheme	What it is	Where it applies
workosSession	WorkOS AuthKit session cookie mcp_session (+ org membership/ownership checks)	CP /api/v1/orgs/*, /api/v1/billing/*. Also accepted on the tenant surface via the CP-session path.
cpAdminBearer	CP CP_ADMIN_API_TOKEN operator bearer (AdminGate, constant-time)	CP /api/v1/admin/* — admin-create-org, tenant teardown, workspace env, ListOrgWorkspaces, redeploy, pins.
provisionSecret	CP PROVISION_SHARED_SECRET bearer	CP /api/v1/workspaces/provision, …/status. Routes unmounted when the secret is unset.
tenantAdminToken	Per-tenant admin_token (+ X-Molecule-Org-Id)	CP DELETE /api/v1/workspaces/:id (deprovision) — in addition to provisionSecret (issue #118).
orgApiKey	Tenant Org API Key — Authorization: Bearer <key> + routing header; full tenant-admin, self-minting	All tenant routes: /workspaces[/:id], /workspaces/:id/secrets, budget, billing-mode, /settings/secrets, /org/import, /org/templates, /org/tokens, /templates, /bundles.
workspaceToken	Per-workspace bearer, bound to one workspace id (+ routing header)	Read/lifecycle/secrets on a single /workspaces/:id/*. Rejected on admin list/create/delete when ADMIN_TOKEN is set — use orgApiKey.
orgRoutingHeaderId / orgRoutingHeaderSlug	X-Molecule-Org-Id / X-Molecule-Org-Slug	Required on every tenant-host request so the edge / TenantGuard route + authorize against the correct org. Send one of them alongside the bearer.

Guards worth knowing (modelled per-operation)

• Dry-run: POST /api/v1/admin/orgs?dry_run=true — validate + echo, no org created. (The only dry-run on the whole management API.)
• Confirm token: DELETE /api/v1/admin/tenants/:slug and …/scrub-artifacts — body confirm MUST equal the URL slug, else 400 before any teardown.
• Force flag: POST /api/v1/admin/workspaces/:id/env — keys matching the secret-keyword guard (TOKEN/SECRET/KEY/PASSWORD) require force=true.
• Runtime-pin gate: POST /api/v1/workspaces/provision returns 422 RUNTIME_PIN_MISSING when no runtime image pin exists.
• Auto-restart side-effects: writing a workspace or global secret auto-restarts the affected workspace(s).

Security note (carried from the synthesis spec)

The Org API Key is full tenant-admin and self-minting — a management MCP holding one holds tenant root. There is no scope-down today (TODO in orgtoken). Per-role / per-workspace scoping should ship alongside the management MCP.

Validate

cd workspace-server/docs/openapi
npx @redocly/cli lint management.yaml   # must be clean (0 errors, 0 warnings)

Scope notes / best-effort flags

• The per-workspace runtime surface (schedules, agent, registry, a2a, memory, approvals, channels, terminal, files) is intentionally out of scope here — that's the runtime contract, not management.
• A handful of bodies are best-effort from the handlers (org-import inline template, bundle import, list responses with open shapes) and are marked with additionalProperties: true in the schema. Tighten as the handler structs stabilise.
• /cp/* deprecated mirrors are omitted (identical shapes; RFC #61 Deprecation/Sunset). Build against /api/v1/*.