molecule-core/docs/blog/2026-04-21-org-scoped-api-keys/index.md

title	date	slug	description	tags
Org-Scoped API Keys: Enterprise Key Management for Multi-Agent Teams	2026-04-21	org-scoped-api-keys	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.	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

curl -X POST https://platform.moleculesai.app/org/tokens \
  -H "Authorization: Bearer <your-session-token>" \
  -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:

{
  "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

curl https://platform.moleculesai.app/org/tokens \
  -H "Authorization: Bearer <your-session-token>"

Returns key IDs, names, prefixes, and creation timestamps — no plaintext.

Revoke a key immediately

curl -X DELETE https://platform.moleculesai.app/org/tokens/tok_01HXYZ... \
  -H "Authorization: Bearer <your-session-token>"

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 → Platform API Reference

---

Molecule AI is open source. Org-scoped API keys shipped in PRs #1105, #1107, #1109, and #1110.