From 274a0b67276aa70d87ff0359d531cb6a031ca9f4 Mon Sep 17 00:00:00 2001 From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com> Date: Tue, 21 Apr 2026 08:26:50 +0000 Subject: [PATCH] docs(blog): add org-scoped API keys enterprise key management post Adds the org-scoped API keys blog post (extracted from orphaned PR #1342). Already live on Molecule-AI/docs main at content/blog/2026-04-20-org-api-keys. Molecule AI is open source. Org-scoped API keys shipped in PRs #1105, #1107, #1109, and #1110. --- .../2026-04-21-org-scoped-api-keys/index.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/blog/2026-04-21-org-scoped-api-keys/index.md diff --git a/docs/blog/2026-04-21-org-scoped-api-keys/index.md b/docs/blog/2026-04-21-org-scoped-api-keys/index.md new file mode 100644 index 00000000..2559cc32 --- /dev/null +++ b/docs/blog/2026-04-21-org-scoped-api-keys/index.md @@ -0,0 +1,138 @@ +--- +title: "Org-Scoped API Keys: Enterprise Key Management for Multi-Agent Teams" +date: 2026-04-21 +slug: org-scoped-api-keys +description: "Named, revocable, audit-trail-enabled tokens for every integration in your organization. Replace shared ADMIN_TOKEN with org-level keys that rotate without downtime and trace every call back to the key that made it." +tags: [security, enterprise, API-keys, multi-agent, audit] +--- + +# Org-Scoped API Keys: Enterprise Key Management for Multi-Agent Teams + +When your engineering team scales from two agents to twenty, the last thing you want is a single `ADMIN_TOKEN` hardcoded in your environment. It's a single point of failure, impossible to rotate without downtime, and impossible to audit. Today's launch changes that. + +Molecule AI is rolling out **org-scoped API keys** — named, revocable, audit-trail-enabled tokens that live at the organization level and reach every workspace in your org without breaking the security model. + +## What Are Org-Scoped API Keys? + +Org-scoped API keys are long-lived credentials minted at the organization level via the Canvas UI or the REST API. Each key has: + +- A **display name** you choose at creation time (e.g., `ci-deploy-bot`, `devops-rev-proxy`) +- A **sha256 hash** stored server-side — the plaintext is shown once and never again +- A **prefix** (first 8 chars) visible in listings so you can identify keys without exposing secrets +- A **created-by** field that tracks provenance in the audit trail +- **Immediate revocation** — drop a key and it stops being accepted on the very next request + +The keys work across all workspaces in your org — not just admin-surface endpoints, but also per-workspace sub-routes like `/workspaces/:id/channels` and `/workspaces/:id/secrets`. + +## The `ADMIN_TOKEN` Problem + +A single env-var token works for prototypes. For production multi-agent systems it creates three compounding risks: + +1. **Rotation requires downtime.** You can't rotate a token used by ten agents simultaneously. You rotate, or you don't — and both choices are bad. +2. **No attribution.** When something calls your API, you have no idea which agent or integration is responsible. +3. **No compartmentalization.** One compromised token compromises everything. + +Org-scoped keys give each integration its own credential with its own identity. The table below summarizes the difference: + +| Capability | Shared `ADMIN_TOKEN` | Org-Scoped Keys | +|---|---|---| +| Rotate without downtime | ❌ | ✅ | +| Identify caller per request | ❌ | ✅ | +| Revoke a single integration | ❌ | ✅ | +| Use on workspace sub-routes | ❌ | ✅ | +| Full audit trail with attribution | Partial | ✅ | + +## How to Create and Revoke Keys + +### Mint a key via API + +```bash +curl -X POST https://platform.moleculeai.ai/org/tokens \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "name": "ci-deploy-bot" + }' +``` + +The response contains the plaintext token — shown exactly once. Store it immediately; the platform never stores or retrieves the plaintext, only the SHA-256 hash: + +```json +{ + "id": "tok_01HXYZ...", + "name": "ci-deploy-bot", + "prefix": "mole_a1b2", + "auth_token": "eXzKpL9...", + "warning": "copy this token now; it will not be shown again" +} +``` + +### List active keys + +```bash +curl https://platform.moleculeai.ai/org/tokens \ + -H "Authorization: Bearer " +``` + +Returns key IDs, names, prefixes, and creation timestamps — no plaintext. + +### Revoke a key immediately + +```bash +curl -X DELETE https://platform.moleculeai.ai/org/tokens/tok_01HXYZ... \ + -H "Authorization: Bearer " +``` + +The key stops being accepted on the very next request. No grace period, no cooldown. + +## Audit Trail and Attribution + +Every request authenticated with an org API key carries the key's prefix in the audit log: + +``` +org-token:mole_a1b2 POST /workspaces/ws_abc123/channels 200 12ms +org-token:mole_a1b2 GET /workspaces/ws_abc123/secrets 200 3ms +``` + +When combined with the `created_by` field stored at mint time, you get full provenance: which admin created this key, when, and what it has been calling. If a CI pipeline key is compromised, revoke it in one API call and know exactly which calls it made. + +## Key Use Cases + +### Team API keys + +Give each team its own named key. The `devops-rev-proxy` key only talks to the observability stack; the `data-pipeline` key only accesses workspaces running the data pipeline agent. If one key is compromised, revoke it without touching the others. + +### Service accounts + +Long-running integrations — CI pipelines, external monitoring tools, backup scripts — get their own credential scoped to exactly the endpoints they need. Rotate on a schedule without coordinating downtime with other integrations. + +### Key rotation without downtime + +When you need to rotate a key, mint a new one, update your integration, and revoke the old one. Both keys are valid simultaneously during the window when you're updating the integration — zero downtime, full audit trail. + +## Authentication Tier Reference + +Org API keys sit in a defined priority hierarchy: + +| Tier | Auth method | Use case | +|---|---|---| +| 0 | Lazy bootstrap | Only active when no org tokens and no `ADMIN_TOKEN` exist | +| 1 | WorkOS session | Human users authenticated via the Canvas | +| 2a | Org API token | New org-scoped keys — primary path for service integrations | +| 2b | `ADMIN_TOKEN` env var | Break-glass for operators and CLI tooling | +| 3 | Workspace tokens | Deprecated — use org tokens instead | + +When a request arrives, the platform checks tiers in priority order. An org API key bypasses workspace-auth middleware and reaches any workspace in the org. + +## Get Started + +Navigate to **Settings → Org API Keys** in the Canvas to mint your first key, or use the REST API directly. Store the plaintext when it is returned — it will not be shown again. Use the key prefix in your observability pipeline to trace calls back to the key that made them. + +Revoke and rotate at any time from the same screen. + +→ [Canvas → Settings → Org API Keys](https://canvas.moleculeai.ai) +→ [Platform API Reference](/docs/api-protocol/platform-api) + +--- + +*Molecule AI is open source. Org-scoped API keys shipped in PRs #1105, #1107, #1109, and #1110.* \ No newline at end of file