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.
This commit is contained in:
molecule-ai[bot]
GitHub
parent
bde456a893
commit
274a0b6727
138
docs/blog/2026-04-21-org-scoped-api-keys/index.md
Normal file
138
docs/blog/2026-04-21-org-scoped-api-keys/index.md
Normal file
@ -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 <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:
|
||||
|
||||
```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 <your-session-token>"
|
||||
```
|
||||
|
||||
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 <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](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.*
|
||||
Loading…
Reference in New Issue
Block a user