0026. Workspace roles, project API keys, and MCP grant scopes
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”ADR 0005 requires scoped API keys and OAuth for MCP, and left scope names open. Keys used in browsers and mobile apps are public and will be abused. Users with several projects connect one AI assistant.
Decision
Section titled “Decision”Workspace roles:
| Role | Can |
|---|---|
| owner | everything an admin can, plus billing, deleting or transferring the workspace, sending domains, and managing admins |
| admin | everything a member can, plus members, API keys, webhook secrets, activating and stopping workflows, export and bulk delete, and the audit log |
| member | drafts, test runs, viewing and editing data |
Amendment (2026-11-19, ADR 0041, decided by the maintainer): there is no owner role. The workspace roles are admin and member. Everything the owner row lists (billing, deleting the workspace, sending domains, managing admins) is admin’s, and transferring the workspace goes away with the role. A workspace always keeps at least one admin. Where this ADR, its amendments included, says owner, read admin. ADR 0041 is now Accepted, so the amendment below that is marked pending it holds.
Project API keys:
| Prefix | Kind | Access |
|---|---|---|
cl_sk_ |
secret | full API for the project |
cl_rk_ |
restricted | the scopes chosen at creation |
cl_pk_ |
publishable | events for existing customers and anonymous events only |
cl_whsec_ |
webhook signing secret | signs our outbound webhooks so receivers can verify them |
Amendment (2026-11-13, ADR 0033): send approval link secrets carry the prefix cl_apsec_. They are not API keys; the prefix lets log redaction and secret scanners recognize them.
Amendment (2026-11-13, ADR 0036): one-click unsubscribe tokens carry the prefix cl_unsub_, for the same reason. They are not API keys either.
- Publishable keys cannot create customers or change emails, accept only allowlisted event names, and are rate limited per key and per IP with a daily cap. Their events are tagged with their provenance and cannot trigger send-capable workflows or satisfy conditions unless the workflow opts in. Optional HMAC identity verification lets the user’s backend vouch for a customer ID.
- Every key and secret is returned in plaintext only in the response that creates it (creation or rotation) and is redacted everywhere else: other API and MCP responses, logs, and step logs show only its prefix and last four characters. Keys and secrets are prefixed so secret scanners recognize them. API keys are stored hashed and record a coarse last-used time;
cl_whsec_secrets are stored encrypted because signing needs the plaintext (ADR 0021). Key lookups use a short-TTL cache. Rotation supports an overlap period, and keys can expire.
MCP grants:
- Scopes are
read,write,send, andadmin. A grant is bound to one project. - The effective permission of every request is the grant’s scope intersected with the user’s current role, computed per request, so a demoted user loses access immediately.
Audit log:
- Each workspace has an audit log in D1, kept about one year, then archived to R2.
Consequences
Section titled “Consequences”- The OAuth implementation is in ADR 0025, which stays Proposed until its spike passes.
- Action definitions declare both the required scope and the required role (ADR 0019).
Amendment (2026-11-18, ADR 0040): ADR 0025 is superseded by ADR 0040, which accepts sign-in and sessions; MCP OAuth waits for its own spike of @better-auth/oauth-provider.
Amendment (2026-11-18, pending ADR 0044, Proposed): pausing a workflow or a project’s sending is open to member (scope write), because it is the safe direction; resuming and rolling back need admin, like activating. Changing whether send approval is required is an owner’s, by session only.
Amendment (2026-11-18, pending ADR 0041, Proposed): actions that need a signed-in user (workspaces, projects, API key management) stay MCP tools, and answer forbidden to project keys and to MCP grants. A grant reaches only actions open to every principal, with its scope ∩ the user’s role.
Amendment (2026-11-20, pending ADR 0051, Proposed): MCP grant tokens carry the prefixes cl_oat_ (access) and cl_ort_ (refresh), and OAuth authorization codes cl_oac_; all are stored hashed, except that a refresh rotation’s response is kept encrypted, from rotation until it is cleared, with the auth secret (ADR 0051, amending ADR 0021). The user chooses a grant’s project and scopes on the consent page, within the scopes their role allows, with only read and write preselected.