Platform Management API
Manage Molecule organizations, workspaces, secrets, templates, and API keys over HTTP. The two-service architecture, the credential model, and task-oriented guides — with CLI and MCP equivalents.
Platform Management API
This is the developer-facing guide to managing a Molecule deployment over HTTP — provisioning workspaces, setting secrets, minting API keys, creating organizations from templates, and configuring billing. It covers the auth model, a task-oriented cookbook, and the machine-readable contract.
This guide is the prose layer. The machine-readable contract is the
OpenAPI spec at
workspace-server/docs/openapi/management.yaml
in molecule-core — endpoint shapes (paths, request bodies, response schemas)
derive from that file, not from this page. When this guide and the spec
disagree, the spec wins. Anything this guide marks "verify against handler"
is a known-uncertain detail to confirm against the spec or the route handler
before you depend on it.
The one structural fact: two services, two auth stacks
Molecule is not one API. It is two services with two separate auth stacks, and the single most common integration mistake is presenting a credential to the wrong host.
Control plane (CP)
- Host:
api.moleculesai.app - Route prefixes:
/api/v1/*(stable, versioned — build against this) and/cp/*(the older, identical surface; sunset-headed) - Owns: organizations, members, billing, provisioning, fleet operations — everything that exists above a single org.
- Auth tiers: WorkOS session cookie, CP admin bearer
(
CP_ADMIN_API_TOKEN), provision shared-secret, tenant-admin-token.
Tenant platform (per-org workspace server)
- Host:
<org-slug>.moleculesai.app(one EC2 per org — e.g.agents-team.moleculesai.app) - Owns: workspaces, agents, secrets, templates, org tokens, bundles, channels — everything inside one org.
- Auth tiers: Org API Key (
org_api_tokens), per-workspace token,ADMIN_TOKEN, and verified CP-session cookie — all behindTenantGuard(which matches theX-Molecule-Org-Idrouting header to the host).
When to call which host
| You want to… | Call | Credential |
|---|---|---|
| Create / delete an org, manage members, billing | CP api.moleculesai.app | WorkOS session (ownership) |
| Fleet ops, tenant teardown, workspace env force-set, image pins | CP /api/v1/admin/* (/cp/admin/* is the older identical alias) | CP admin bearer |
| Provision / deprovision a workspace EC2-side | CP /api/v1/workspaces/* | provision-secret (+ X-Molecule-Admin-Token to deprovision) |
| List / create / restart workspaces, set secrets, mint org keys, import templates | Tenant <slug>.moleculesai.app | Org API Key (most common) |
| Look up an org's routing host (public) | CP GET /api/v1/orgs/:slug/instance | none (public) |
The Org API Key — the credential you create under dashboard Settings → Org API Keys — is a tenant credential, not a CP one. It authorizes the entire tenant-admin surface of its own org and nothing on the CP. Org create/delete, members, billing, and provisioning all reject it (401/403). See Auth model.
Where to go next
- Getting started — the Org API Key path, the most common developer entry point. Start here.
- Auth model — every credential type, how to obtain each, and the full credential → route tier matrix.
- Task guides — provision a workspace, set a secret, mint/revoke an Org API Key, create an org from a template, set billing-mode and budget. Each with the exact request plus CLI and MCP equivalents.
- Reference & OpenAPI contract — the machine-readable spec and the per-surface endpoint summary.
Related existing docs
This guide ties together several existing references; consult them for depth:
- Org-Scoped API Keys — mint/audit/revoke walkthrough.
- Token Management API — per-workspace bearer tokens.
- ADMIN_TOKEN — Production Requirement — the break-glass tenant credential.
- Org Templates — define a whole org in one YAML file.
- Platform API (Go Backend) — tenant route tables.
- API Reference — the full endpoint listing.
- MCP Server Setup — connect an MCP client.
Real-time & Observability API
Canvas, traces, audit ledger, events, terminal, WebSocket, and Server-Sent Events endpoints.
Getting Started (Org API Key)
The most common developer entry point to the Molecule Management API — mint an Org API Key, call the tenant host, and understand the tenant-root security caveat.