Auth Model

Molecule's management surface spans two services, each with its own auth stack. This page enumerates every credential type, how to obtain it, and exactly which routes it authorizes.

The six credential types

1. WorkOS session cookie

• Service: Control plane (api.moleculesai.app).
• What it is: the browser AuthKit session set after a user signs in through the dashboard. Carries user identity and org ownership/membership.
• How to obtain: sign in via /auth/login (AuthKit/WorkOS); the session cookie is set by the /auth/callback redirect. The dashboard sends it automatically.
• Authorizes: the human-owner CP surface — create/delete orgs, manage members, billing, and (proxied) tenant operations. This is the dashboard's credential, not a headless-integration credential.
• Header: sent as a cookie, plus X-Molecule-Org-Slug for org-scoped routes.

2. CP admin bearer (CP_ADMIN_API_TOKEN)

• Service: Control plane, /api/v1/admin/* (/cp/admin/* is the older, identical alias).
• What it is: the platform-operator master token for fleet operations.
• How to obtain: set as an environment variable on the control plane; held by platform operators only. Not user-facing.
• Authorizes: fleet ops, tenant teardown, force-setting workspace env, image/AMI pins, reapers, beta allowlist. (LLM billing-mode is not a CP route — it lives on the tenant, behind an Org API Key.)
• Header: Authorization: Bearer <CP_ADMIN_API_TOKEN>.

3. Provision shared-secret (+ tenant-admin-token)

• Service: Control plane, /api/v1/workspaces/provision|:id (the /cp/workspaces/* prefix is the older, identical alias).
• What it is: a shared secret that gates the EC2-side provisioning path. Deprovision additionally requires the target org's tenant-admin-token.
• How to obtain: provisioning is normally driven by the platform itself; the tenant-admin-token for an org is read from CP admin (GET /api/v1/admin/orgs/:slug/admin-token, CP-admin-bearer gated).
• Authorizes: only POST /api/v1/workspaces/provision, DELETE /api/v1/workspaces/:id, and GET …/status. Nothing else.
• Header: the provision secret as Authorization: Bearer <secret>. Deprovision adds the per-tenant admin token in X-Molecule-Admin-Token (not Authorization, not X-Molecule-Org-Id).

4. Org API Key (org_api_tokens) — the common one

• Service: Tenant (<org-slug>.moleculesai.app).
• What it is: a named, sha256-hashed, prefixed, revocable token that grants full tenant-admin over its own org. This is the credential behind dashboard Settings → Org API Keys.
• How to obtain: mint via the dashboard, or POST /org/tokens on the tenant host (authorized by an existing Org API Key, ADMIN_TOKEN, or a CP session). The plaintext is shown once. See Getting started.
• Authorizes: the entire tenant-admin surface of its org — workspaces (list/create/delete/restart), secrets (workspace and org), per-workspace billing-mode and budget, templates, bundles, org tokens, plugin allowlist. Reaches nothing on the CP.
• Header: Authorization: Bearer <key> and X-Molecule-Org-Id: <orgId> to the tenant host.

5. Per-workspace token

• Service: Tenant, /workspaces/:id/*.
• What it is: a bearer token bound to a single workspace; a token for workspace A cannot touch workspace B.
• How to obtain: issued during workspace registration (POST /registry/register). Two mint routes exist: POST /workspaces/:id/tokens (WorkspaceAuth — self-service, from a token already bound to that workspace) and POST /admin/workspaces/:id/tokens (AdminAuth — Org API Key / ADMIN_TOKEN, the route the management MCP/CLI uses). List with GET /workspaces/:id/tokens. See Token Management API.
• Authorizes: run/secrets/config/restart on the bound workspace only. It is rejected on tenant-admin routes (list/create/delete workspaces, org secrets, org import, templates import, bundles) when ADMIN_TOKEN is set.
• Header: Authorization: Bearer <workspace-token>.

6. ADMIN_TOKEN (tenant)

• Service: Tenant.
• What it is: the per-tenant break-glass bootstrap credential set as an environment variable on the workspace server. Required in production.
• How to obtain: configured at deploy time. See ADMIN_TOKEN — Production Requirement.
• Authorizes: the full tenant surface (same reach as an Org API Key). Use it to mint the first Org API Key, then prefer scoped Org API Keys for day-to-day work.
• Header: Authorization: Bearer <ADMIN_TOKEN>.

Credential → route tier matrix

Read this as: for a given route surface (rows), which credentials (columns) are accepted. ✓ = accepted; ✗ = rejected (401/403); — = not applicable to that service; public = no auth required.

Notes:

• All bearer-token gates use constant-time comparison.
• Tenant gates fail-open only on a fresh self-host / dev boot — never on hosted SaaS.
• GET /api/v1/orgs/:slug/instance is genuinely public — it is a routing lookup, not an authenticated read. A 200 from it does not imply your key is valid.
• An Org API Key can mint/revoke more Org API Keys via /org/tokens; revoke with DELETE /org/tokens/:id.
• There is no scope-down below full-admin yet (planned — see Scoped roles).

Picking the right credential

• Headless integration scoped to one org → Org API Key. This is the default. (Getting started.)
• An agent that should only touch its own workspace → per-workspace token.
• Per-workspace billing-mode and budget automation → Org API Key (these are tenant routes — /admin/workspaces/:id/llm-billing-mode and /workspaces/:id/budget — not CP-session). See the reference.
• Workspace provisioning / deprovisioning → provision shared-secret tier (credential #3), not CP-session.
• Org create/delete, member management, and the billing portal/subscription → CP session tier (the Org API Key cannot reach these). Today this means driving the dashboard's session-authed /cp/* proxy.
• Platform-operator fleet work → CP admin bearer. Operators only.