00a0fc91fe
The monorepo docs/ tree is ecosystem + user-facing. Internal
roadmap ("what we'll build next", priorities, effort estimates)
doesn't belong there — customers reading our docs don't need our
backlog in their face, and we shouldn't signal "feature X is
coming" contractually when it's just a P2 item in internal
tracking.
Removes:
- docs/architecture/org-api-keys-followups.md (the whole
prioritized roadmap). Moved to the internal repo at
runbooks/org-api-keys-followups.md where it belongs.
- "Follow-up roadmap" section in docs/architecture/org-api-
keys.md, replaced with a shorter "Known limitations" section
that names the current constraints (full-admin only, no
expiry, no user_id in session-minted audit) without
speculating on when they change.
- "What's coming" section in docs/guides/org-api-keys.md,
replaced with "Current limits" that names the same
constraints from the user's POV.
Public docs now describe the feature as it exists TODAY. Internal
tracking of what comes next lives in Molecule-AI/internal (private).
139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer $MOLECULE_ORG_TOKEN" \
|
|
https://acme.moleculesai.app/workspaces
|
|
```
|
|
|
|
### Python
|
|
|
|
```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
|
|
|
|
```ts
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Current limits
|
|
|
|
Every key is full-admin. Scoped roles (read-only / workspace-
|
|
write / admin), per-workspace bindings, and expiry are not yet
|
|
supported — treat every key as equivalent to being logged in.
|