molecule-core/docs/guides/org-api-keys.md

Organization API Keys — User Guide

Full-admin API keys for your Molecule AI organization. Use these to let AI agents, scripts, or integrations manage your org without a browser session.

TL;DR

1. Open your org's canvas UI (https://<your-slug>.moleculesai.app)
2. Settings (⌘,) → Org API Keys tab
3. Click New Key, give it a label (e.g. "zapier", "my-claude-agent")
4. Copy the token immediately — it will never be shown again
5. Hand it to whatever needs org-admin access:

   Authorization: Bearer <your-token>
   

Revoke from the same UI the moment anything looks wrong.

What these keys can do

Full organization admin. A valid org API key is equivalent to being logged in as an admin user. With it, a script or AI can:

• Create, delete, list workspaces
• Import a complete org definition (can wipe + recreate everything)
• Manage per-workspace secrets (your OpenAI/Anthropic/etc. keys)
• Register + install templates, bundles, plugins
• Approve or reject pending workspace approvals
• Configure channels (Slack, Discord, etc.)
• Mint more org API keys
• Revoke any org API key (including itself)

What they cannot do:

• Reach the control plane's admin API (/cp/admin/*) — CP admin lives on a separate allowlist.
• Touch other organizations — each org's keys work only on its own tenant.
• Edit the tenant's environment variables or restart the underlying EC2 instance — those are ops-only operations.

Treat keys like passwords

• Don't commit keys to git. If you must have one in source, reference an env var and keep the var in your secret manager.
• Don't paste keys into Slack or email. Share via a password manager when you can.
• Do give each integration its own key with a descriptive name. If Zapier gets compromised, you revoke zapier and leave github-action-deploy untouched.
• Do revoke any key you stop using.

If you leak one, revoke it and mint a new one. Revocation is immediate — the next request with the old key gets 401.

Using a key

curl

curl -H "Authorization: Bearer $MOLECULE_ORG_TOKEN" \
  https://acme.moleculesai.app/workspaces

Python

import os, requests

resp = requests.get(
    "https://acme.moleculesai.app/workspaces",
    headers={"Authorization": f"Bearer {os.environ['MOLECULE_ORG_TOKEN']}"},
)
resp.raise_for_status()
print(resp.json())

TypeScript / Node

const resp = await fetch("https://acme.moleculesai.app/workspaces", {
  headers: { Authorization: `Bearer ${process.env.MOLECULE_ORG_TOKEN}` },
});
if (!resp.ok) throw new Error(`${resp.status}: ${await resp.text()}`);
console.log(await resp.json());

Hand it to an AI agent

Add the key to the agent's environment or config, with clear instructions about what routes it should touch. Claude Code, for example, can use it to inspect the tenant's state programmatically:

export MOLECULE_ORG_TOKEN=...   # the key you just minted

Then tell the agent: "Using MOLECULE_ORG_TOKEN, list my workspaces and tell me which ones are idle."

Endpoints you'll hit most often

Method	Path	What it does
GET	/workspaces	list all workspaces
POST	/workspaces	create a workspace
DELETE	/workspaces/:id	delete a workspace
GET	/org/templates	list registered templates
POST	/org/import	import a full org YAML
POST	/bundles/import	install a bundle
GET	/approvals/pending	list pending approvals

Each workspace you create gets its own workspace-scoped token returned in the create response. Use that token (not the org key) for agent-to-platform calls inside that specific workspace — it has a narrower blast radius if leaked.

Full API reference: docs/api-reference.md.

Keys vs session cookies

	Org API Key	WorkOS session cookie
Who holds it	Integrations, AI, CLI	Your browser
Where you see it	/org/tokens UI	Browser cookies
Revocation	One-click in UI	Log out / session expiry
Use from code	Yes	No (HttpOnly)
Blast radius	Full org admin	Full org admin

Both unlock the same surface; the key is just the non-browser equivalent.

What's coming

Scoped roles (READ / WORKSPACE-WRITE / ORG-ADMIN), expiry timers, per-workspace bindings, and usage metrics are on the roadmap. See docs/architecture/org-api-keys-followups.md. For now every key is full-admin by design — trading scope granularity for beta shipping speed.