Getting Started with an Org API Key

The Org API Key is the most common developer entry point to Molecule's management surface. It is a tenant credential that grants full admin over your own organization — workspaces, secrets, templates, bundles, and org tokens — through your org's tenant host. This page gets you from zero to your first authenticated call.

Prerequisites

• An organization (slug, e.g. acme). Its tenant host is acme.moleculesai.app.
• One bootstrap credential to mint the first key — either a signed-in dashboard session, or the tenant ADMIN_TOKEN (what that is).

Step 1 — Mint an Org API Key

Dashboard

Settings → Org API Keys → Mint new key, name it (e.g. ci-bot), and copy the plaintext token — it is shown once only.

HTTP

curl -X POST https://acme.moleculesai.app/org/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "X-Molecule-Org-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-bot"}'

{
  "id": "tok_01HZX3B7N8PQ9K4M5R6T",
  "name": "ci-bot",
  "prefix": "mola_k7x9p2q4",
  "auth_token": "mola_k7x9p2q4r8s1t3u5v6w0x2y3z",
  "created_by": "admin-token",
  "created_at": "2026-06-01T00:00:00Z"
}

Save the auth_token value immediately — the plaintext is shown once and is never returned again. Store it as MOLECULE_ORG_TOKEN. (The prefix is a non-secret identifier you can use to recognize the key later; subsequent list calls return only id/prefix/metadata, never auth_token.)

Step 2 — Find your tenant host (optional)

The org's routing host is a public CP lookup — no auth required:

curl https://api.moleculesai.app/api/v1/orgs/acme/instance

The response gives the tenant hostname you address for every tenant call.

Step 3 — Make your first authenticated call

Every tenant call needs two headers: the bearer key and the org-id routing header.

curl https://acme.moleculesai.app/workspaces \
  -H "Authorization: Bearer $MOLECULE_ORG_TOKEN" \
  -H "X-Molecule-Org-Id: $ORG_ID"

That lists your org's workspaces. From here, see the task guides for provisioning, secrets, templates, and billing.

Step 4 — Use it from the CLI or an MCP client

• CLI: the molecule CLI authenticates with MOLECULE_API_KEY (your Org API Key). See task guides for per-task verbs.

  The current molecule CLI's runHTTP path does not attach an Authorization header, so its workspace create/delete verbs will 401 against a hardened tenant. Fixing this (attach Authorization: Bearer $MOLECULE_API_KEY) is the first item on the CLI roadmap — verify against the CLI source before relying on a given verb.

• MCP: point an MCP client at your org by setting MOLECULE_API_KEY plus the org headers. See MCP Server Setup. Note that today's MCP server is single-tenant workspace-ops; org-lifecycle, cross-org, member, and billing tools are not part of it.

What an Org API Key can and cannot do

Can (full tenant-admin over its own org):

• Create, delete, inspect, restart/pause/resume all workspaces
• Set workspace and org-wide secrets
• Import/export org definitions and bundles; import templates
• Manage the plugin allowlist
• Mint and revoke other Org API Keys
• Approve/reject pending workspace requests

Cannot (all reject it):

• Anything on the control plane — org create/delete, members, billing, provisioning, fleet ops (/api/v1/admin/*, /api/v1/orgs/*)
• Cross into any other organization

Security: tenant root

Practical consequences:

• An MCP server or CI job holding an Org API Key holds tenant root. Scope the blast radius accordingly — dedicated key per integration, least number of holders, rotate on suspicion.
• Prefer per-workspace tokens when an agent only needs its own workspace — they are bound to a single :id and cannot reach the admin surface. See Token Management API.
• Keep ADMIN_TOKEN as break-glass, not as a day-to-day credential; mint named Org API Keys instead so usage is attributable and revocable.
• Revoke instantly with DELETE /org/tokens/:id — revocation takes effect on the next request, not after a background sweep.

Per-role / per-workspace scoping is planned to ship alongside a dedicated management MCP. Until then, treat every Org API Key as a tenant-root secret.