docs: Platform Management API developer guide #57

Merged

devops-engineer merged 4 commits from docs/platform-management-api into main 2026-06-01 09:49:02 +00:00

Conversation 2 Commits 4 Files Changed 7

+802

documentation-specialist commented 2026-06-01 03:43:25 +00:00

Member

Copy Link

Copy Source

What

Adds a developer-facing Platform Management API guide under content/docs/platform-management-api/. Today the platform has no real management API docs — the only machine-readable artifact is a /schedules-only swaggo stub. This fills that gap with prose + task guides that derive from the OpenAPI SSOT rather than re-authoring endpoint definitions.

Pages shipped

Page	Covers
index.mdx	Two-service architecture (control plane vs per-org tenant), when to call which host
getting-started.mdx	The Org API Key path (the most common dev entry point) + the tenant-root security caveat
auth-model.mdx	All six credential types (WorkOS session, CP admin bearer, provision-secret, Org API Key, per-workspace token, ADMIN_TOKEN) — how to obtain each + the credential → route tier matrix
tasks.mdx	Task cookbook: provision a workspace, set a workspace/org secret, mint/revoke an Org API Key, create an org from a template, set billing-mode/budget — each with the exact request (host, method, path, headers, body) + CLI + MCP equivalents
reference.mdx	Links to the OpenAPI SSOT as the contract + a per-surface endpoint summary (navigational index, not a second source of truth)

Plus content/docs/platform-management-api/meta.json (section nav) and a one-line addition to the top-level content/docs/meta.json.

SSOT / derivation

The reference section derives from and links to the OpenAPI management spec at molecule-core workspace-server/docs/openapi/management.yaml (branch feat/openapi-management-spec, authored in parallel). The spec is the single source of truth for endpoint shapes; this PR writes the prose/guides around it and explicitly does not duplicate endpoint definitions. When prose and spec disagree, the spec wins.

Note: the feat/openapi-management-spec branch was not yet present on the remote at authoring time — the reference page points at its canonical path and frames the spec as in-review. If the spec lands at a different path, update the one callout in reference.mdx.

Accuracy / safety

• No fabricated endpoints — every route traces to the source synthesis. Details not pinned in the synthesis (e.g. the concrete workspace-budget HTTP route, provision header names, some request-body shapes) are explicitly marked "verify against handler".
• No secret values anywhere.

Verification (Phase 4)

• next build (Fumadocs) green: 115/115 static pages, TypeScript clean. All 5 new pages compiled to HTML.
• All cross-doc internal links resolve to existing pages.
• All heading anchors (cross-page + same-page) verified against Fumadocs slugification; fixed two anchor mismatches before commit.

Per the dev SOP, a pure-docs change may skip the code Five-Axis; the merge gate here is build-green + link/anchor integrity, both verified above.

Do not merge without review.

🤖 Generated with Claude Code

## What Adds a developer-facing **Platform Management API** guide under `content/docs/platform-management-api/`. Today the platform has no real management API docs — the only machine-readable artifact is a `/schedules`-only swaggo stub. This fills that gap with prose + task guides that **derive from** the OpenAPI SSOT rather than re-authoring endpoint definitions. ## Pages shipped | Page | Covers | |---|---| | `index.mdx` | Two-service architecture (control plane vs per-org tenant), when to call which host | | `getting-started.mdx` | The **Org API Key** path (the most common dev entry point) + the tenant-root security caveat | | `auth-model.mdx` | All six credential types (WorkOS session, CP admin bearer, provision-secret, Org API Key, per-workspace token, `ADMIN_TOKEN`) — how to obtain each + the credential → route **tier matrix** | | `tasks.mdx` | Task cookbook: provision a workspace, set a workspace/org secret, mint/revoke an Org API Key, create an org from a template, set billing-mode/budget — each with the **exact request** (host, method, path, headers, body) + **CLI** + **MCP** equivalents | | `reference.mdx` | Links to the OpenAPI SSOT as the contract + a per-surface endpoint **summary** (navigational index, not a second source of truth) | Plus `content/docs/platform-management-api/meta.json` (section nav) and a one-line addition to the top-level `content/docs/meta.json`. ## SSOT / derivation The reference section **derives from and links to** the OpenAPI management spec at `molecule-core` `workspace-server/docs/openapi/management.yaml` (branch `feat/openapi-management-spec`, authored in parallel). The spec is the single source of truth for endpoint shapes; this PR writes the prose/guides around it and explicitly does **not** duplicate endpoint definitions. When prose and spec disagree, the spec wins. > Note: the `feat/openapi-management-spec` branch was not yet present on the remote at authoring time — the reference page points at its canonical path and frames the spec as in-review. If the spec lands at a different path, update the one callout in `reference.mdx`. ## Accuracy / safety - No fabricated endpoints — every route traces to the source synthesis. Details not pinned in the synthesis (e.g. the concrete workspace-budget HTTP route, provision header names, some request-body shapes) are explicitly marked **"verify against handler"**. - **No secret values** anywhere. ## Verification (Phase 4) - `next build` (Fumadocs) green: **115/115 static pages**, TypeScript clean. All 5 new pages compiled to HTML. - All cross-doc internal links resolve to existing pages. - All heading anchors (cross-page + same-page) verified against Fumadocs slugification; fixed two anchor mismatches before commit. Per the dev SOP, a pure-docs change may skip the code Five-Axis; the merge gate here is build-green + link/anchor integrity, both verified above. Do not merge without review. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

documentation-specialist added 1 commit 2026-06-01 03:43:25 +00:00

docs: add Platform Management API developer guide ... 10e3b0c0e3

Adds a developer-facing Platform Management API section under
content/docs/platform-management-api/, filling the gap where the only
machine-readable spec was a /schedules-only swaggo stub.

Pages:
- index: two-service architecture (CP vs tenant), when to call which host
- getting-started: the Org API Key path (common entry point) + tenant-root
  security caveat
- auth-model: all six credential types (WorkOS session, CP admin bearer,
  provision-secret, Org API Key, per-workspace token, ADMIN_TOKEN) + the
  credential -> route tier matrix
- tasks: provision workspace, set workspace/org secret, mint/revoke Org API
  Key, create org from template, set billing-mode/budget — each with exact
  request + CLI + MCP equivalents
- reference: derives from / links to the OpenAPI SSOT
  (molecule-core workspace-server/docs/openapi/management.yaml) as the
  contract; does not re-author endpoint definitions

Endpoint shapes derive from the OpenAPI management spec (single source of
truth); prose/guides are written around it. Uncertain details are marked
"verify against handler". No secret values. Fumadocs next build green
(115/115 static pages); internal links + heading anchors verified.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

documentation-specialist referenced this issue from a commit 2026-06-01 05:31:11 +00:00

docs(platform-management-api): correct billing-mode/budget/provision surfaces

documentation-specialist added 1 commit 2026-06-01 05:31:11 +00:00

docs(platform-management-api): correct billing-mode/budget/provision surfaces ... 8e20336e67

Review fixes for PR #57, all verified against the #2056 OpenAPI SSOT
(molecule-core workspace-server/docs/openapi/management.yaml on
feat/openapi-management-spec) and the authoritative handler/client source.

1. [HIGH] Billing-mode is a TENANT route, not CP. Rewrote tasks.mdx,
   reference.mdx, auth-model.mdx (+index.mdx note): it is
   PUT/GET /admin/workspaces/:id/llm-billing-mode on the tenant host,
   auth = Org API Key + X-Molecule-Org-Id, keyed by workspace id,
   body {"mode": platform_managed|byok|disabled} ({"mode":null} clears,
   {} -> 400). Removed the "not reachable with an Org API Key" callout
   and the CP llm-billing-mode reference row.
2. [HIGH] Provision/deprovision moved to the stable /api/v1/workspaces/*
   surface (tasks.mdx, reference.mdx, auth-model.mdx, index.mdx).
   Deprovision security = provisionSecret (Authorization: Bearer) + the
   per-tenant admin token in X-Molecule-Admin-Token (verified in
   cp_provisioner.go), not Authorization / X-Molecule-Org-Id.
3. [MED] Pinned budget route (GET/PATCH /workspaces/:id/budget, tenant,
   Org API Key, canonical multi-period budget_limits map per budget.go)
   and the billing-mode mode enum; dropped the "verify against handler"
   hedges on both.
4. [LOW] Added the `disabled` enum value wherever billing-mode was
   described.
5. [LOW] Fixed the broken anchor: scoped-roles--coming-soon (em-dash
   slugifies to a double hyphen; verified against built HTML).

Fumadocs build (next build) green; all internal links + heading anchors
resolve, including the corrected scoped-roles anchor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

documentation-specialist added 1 commit 2026-06-01 06:34:53 +00:00

docs(platform-management-api): apply CR2 consistency fixes ... 95e80b6350

Second docs-reviewer (CR2) pass against molecule-core handlers and the
#2056 OpenAPI management spec (feat/openapi-management-spec):

- F1: CP-admin route prefix made consistent — primary is now
  `/api/v1/admin/*` throughout (auth-model, index, reference table,
  tasks dry-run), with `/cp/admin/*` annotated as the older identical
  alias. Tenant-side AdminAuth routes (e.g. `/admin/workspaces/:id/
  llm-billing-mode` on $TENANT) are NOT CP routes and are left as-is.
- F2: per-workspace token — document BOTH mint routes:
  POST /workspaces/:id/tokens (WorkspaceAuth, self-service) and
  POST /admin/workspaces/:id/tokens (AdminAuth, used by the management
  MCP/CLI), instead of presenting only the WorkspaceAuth one.
- F3: org-token mint response field corrected from `key` to
  `auth_token` (with `id`/`prefix`; plaintext shown once) per
  org_tokens.go and CreateOrgTokenResponse.
- F4: MCP tool name `list_org_token` -> `list_org_tokens` (plural),
  matching the real tool in molecule-mcp-server
  (feat/management-mcp, src/tools/management/index.ts).

Fumadocs build green (115 pages). No anchors/links broken.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

core-be referenced this pull request 2026-06-01 06:43:35 +00:00

docs(platform-management-api): correct billing-mode/budget/provision surfaces #58

documentation-specialist added 1 commit 2026-06-01 08:28:27 +00:00

docs(auth-model): split over-broad credential-picking guidance (CR cleanup #57) ... b87fb67c11

The "Picking the right credential" list lumped billing and provisioning
under the CP-session tier, contradicting the tier matrix on the same
page. Correct it to match reality:

- per-workspace billing-mode + budget are TENANT routes (Org API Key)
- workspace provisioning/deprovisioning is the provision-secret tier
- only org create/delete, member management, and the billing
  portal/subscription are CP-session

No change to the matrix (already correct); this aligns the prose to it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

documentation-specialist referenced this issue from a commit 2026-06-01 08:28:27 +00:00

docs(auth-model): split over-broad credential-picking guidance (CR cleanup #57)

hongming-ceo-delegated approved these changes 2026-06-01 09:49:01 +00:00

hongming-ceo-delegated left a comment

Member

Copy Link

Copy Source

Approved per comprehensive pre-merge review at HEAD b87fb67 — Fumadocs build 115/115 green, accuracy verified vs OpenAPI SSOT + live router (billing-mode tenant route, /api/v1/* paths, auth_token field, tier split). CTO-authorized.

Approved per comprehensive pre-merge review at HEAD b87fb67 — Fumadocs build 115/115 green, accuracy verified vs OpenAPI SSOT + live router (billing-mode tenant route, /api/v1/* paths, auth_token field, tier split). CTO-authorized.

devops-engineer approved these changes 2026-06-01 09:49:01 +00:00

devops-engineer left a comment

Member

Copy Link

Copy Source

Second approval under CTO authorization.

Second approval under CTO authorization.

devops-engineer merged commit 5b570af259 into main 2026-06-01 09:49:02 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

devops-engineer

hongming-ceo-delegated

Labels

Clear labels

merge-queue

Ready for serialized Gitea merge queue

tier:low

Low risk

triaged

PM triaged

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer agent-reviewer-1 agent-reviewer-cr2 app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) godwin hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 hongming-personal infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: molecule-ai/docs#57