0041. Users, workspace memberships, and the user principal of API actions
- Status: Accepted
- Date: 2026-11-19 (proposed 2026-11-18)
- Amends: ADR 0013, ADR 0016, ADR 0019, ADR 0026 (two workspace roles,
adminandmember; noowner), ADR 0033, ADR 0039, ADR 0040, and ADR 0044 (see Consequences)
Context
Section titled “Context”Every api action today is authenticated by a project key: core/auth mints the ProjectScope from the key’s project, and the action’s auth is always "api_key" (ADR 0019). Sign-in (ADR 0040) adds users. Users belong to workspaces with roles (ADR 0026) and may reach several projects. Some actions have no project at all: creating or listing workspaces, which the open items list as not fitting the ProjectScope contract. Others act on a workspace: the sending-domain actions of ADR 0039. Some must never be done with a project key. An AI assistant or a leaked key that could mint keys or create workspaces would escape the limits that send approval relies on (ADR 0033). Approvers are operator-provisioned addresses until users exist (ADR 0033). Suppression is still kept per project, which is acceptable only while each workspace has one project.
Decision
Section titled “Decision”Tables
Section titled “Tables”In the control plane, next to the users table of ADR 0040:
-
memberships(workspace_id, user_id, role, created_at): primary key(workspace_id, user_id), an index onuser_id, androleone ofadmin,member. -
A workspace always keeps at least one
admin. Removing or demoting a member is one conditional statement, so concurrent requests cannot remove the last two admins at once. For example:DELETE FROM membershipsWHERE workspace_id = ?1 AND user_id = ?2AND (role <> 'admin'OR (SELECT count(*) FROM memberships WHERE workspace_id = ?1 AND role = 'admin') > 1)No row changed answers
conflict. This relies on D1’s single writer; on Postgres the statement locks the workspace row (SELECT … FOR UPDATE) first. -
workspacesgainsnameandcreated_by.api_keysgainscreated_by, a user ID; it is null for keys made before users.
A workspace has two roles, where ADR 0026 had three:
| Role | Can |
|---|---|
admin |
everything a member can, plus members and admins, API keys, webhook secrets, activating and stopping workflows, export and bulk delete, the audit log, sending domains (ADR 0039), whether send approval is required (ADR 0044), the workspace’s settings, billing, and deleting the workspace |
member |
drafts, test runs, viewing and editing data |
- There is no
ownerrole, decided by the maintainer on 2026-11-19. ADR 0026’s owner powers belong toadmin. The product is for indie developers working alone or in small teams (ADR 0014), where a third tier adds a concept, a transfer flow, and more role checks without a separate person to give it to. - Trade-off: any admin can remove or demote another admin, and can change the dangerous settings (sending domains, send approval, billing, deleting the workspace). This is accepted for small teams. Only the last admin cannot be removed.
- Workspace-level powers that bill, destroy, or govern the workspace are session-only. Billing, deleting the workspace, changing workspace settings (
workspaces.setSendApprovalamong them), and managing memberships areprincipal: "user"actions, so no project key and no MCP grant reaches them, whatever its scope. Every later workspace-level action that is destructive or touches billing follows this rule. The one deliberate exception issendingDomains.add,sendingDomains.verify, andsendingDomains.remove, which stayprincipal: "any"as ADR 0039 decides, because no action setsverified; only SES does, after the domain’s DNS proves control. Droppingownertherefore gives keys and grants, as a category, no reach they did not have. Within a team, though, the users whose grant with scopeadmincan write sending domains grow from the owners to every admin, and the users who hold the session-only powers grow the same way. - A separate top tier can be added later by a new ADR without a hard migration: the last-admin rule keeps an admin in every workspace, and
workspaces.created_bynames the user who created it.
Principals
Section titled “Principals”A request has one principal:
| Principal | From | Gives |
|---|---|---|
project_key |
Authorization: Bearer cl_sk_… |
the key’s project and workspace, and the key’s API scopes; no role |
user |
the session cookie, through SessionVerifier |
the user, and every API scope the user’s role in the selected workspace allows |
An MCP OAuth grant, when built, acts as its user. It is bound to the grant’s one project and that project’s workspace. Its permission is the grant’s scopes intersected with the user’s role (ADR 0026). It is accepted only by any actions. A user-only action needs a session, so an assistant holding a grant can no more create keys, workspaces, or projects than one holding a key.
What an action declares
Section titled “What an action declares”ApiAction gains three fields, and principal replaces auth: "api_key":
principal: "project_key" | "user" | "any": who may call it.usermeans a session.anyaccepts a key, a session, or a grant. Any other caller getsforbidden.target: "project" | "workspace" | "actor": what the handler acts on.projecthandlers receive aProjectScope, as today.workspacehandlers receive aWorkspaceScope.actorhandlers receive anActorScope, which holds the user ID only.
role: the least role a session or grant needs (admin>member). It is checked on every request against the current membership, so a demotion applies at once.scopestays the API scope a key or grant needs.
Valid combinations:
| Target | project_key |
session | grant |
|---|---|---|---|
project |
its own project, by scope |
the header’s project, by role |
its project, by scope ∩ role |
workspace |
its project’s workspace, only for actions whose scope is read |
the header’s workspace, by role |
its project’s workspace, by scope ∩ role |
actor |
never | yes | never |
So, on ADR 0039’s actions (target: "workspace", principal: "any"):
sendingDomains.listandsendingDomains.get(scope: read, rolemember) are open to a project key.sendingDomains.add,sendingDomains.verify, andsendingDomains.remove(scope: admin, roleadmin) need an admin’s session, or a grant withadminheld by an admin.
Selecting the project or workspace
Section titled “Selecting the project or workspace”- Inputs never carry a project or workspace ID (ADR 0019). A session names its tenant in a header:
Customer-Lite-Project: <projectId>forprojectactions;Customer-Lite-Workspace: <workspaceId>forworkspaceactions.
core/auth, the only minter of scopes, resolves it in order: the project throughControlStore(which gives its workspace), the user’s membership in that workspace, then the role.- An unknown project or workspace, or one the user is not a member of, answers
not_found, as cross-project access does. - A missing header answers
validation_error. - A role that is too low answers
forbidden.
- An unknown project or workspace, or one the user is not a member of, answers
- A project key and a grant ignore these headers: their project and workspace are fixed. For a grant, a header that names another tenant answers
not_found.
First actions
Section titled “First actions”| Action | Principal | Target | Role | Does |
|---|---|---|---|---|
workspaces.create |
user |
actor |
none | creates a workspace with the caller as admin, with abuse screening on the managed service |
workspaces.list |
user |
actor |
none | the caller’s workspaces, and the caller’s role in each |
projects.create |
user |
workspace |
admin |
creates the workspace’s project |
projects.list |
user |
workspace |
member |
the workspace’s projects |
apiKeys.create, apiKeys.list, apiKeys.revoke |
user |
project |
admin |
project key management; the plaintext appears only in the creating response, as ADR 0026 decides |
- Workspaces per user: a user may create at most
MAX_WORKSPACES_PER_USERworkspaces (configuration, default 3), counted byworkspaces.created_by, so the memberships ofADMIN_EMAILSadmins do not count. The count and the insert are one conditional statement, and over the capworkspaces.createanswersworkspace_limit_reached(422), a new error code. - One project per workspace until suppression is replicated across a workspace’s projects:
projects.createon a workspace that has a project answersconflict. The change that replicates suppression lifts this. - The existing project actions (customers, events, workflows, send approvals) become
principal: "any",target: "project", with the roles of ADR 0026:memberfor reading, editing data, drafts, and test runs;adminfor activating and stopping workflows. - Key management, workspaces, projects, and later memberships and invitations are
useronly. No key and no grant can create a key, a workspace, or a project.
Self-hosted admins and the first user
Section titled “Self-hosted admins and the first user”- An
ADMIN_EMAILSuser isadminof every workspace of the installation, through real membership rows. They are written when such a user is created and when any workspace is created. - The first user, made by ADR 0040’s bootstrap route, has no workspace. Like any user, they create one with
workspaces.create; the dashboard does this as its first step.
Parity
Section titled “Parity”- Every action keeps its REST route, MCP tool, OpenAPI entry, and docs (ADR 0005);
user-only actions stay in MCP too. - A
user-only action called with a project key or a grant answersforbiddenon both surfaces, with the same error, and its description says it needs a signed-in user. Until MCP OAuth exists, that is every MCP call to it. The parity test checks this for everyuser-only action. - The dashboard calls the same
apiactions with its session cookie and the header (ADR 0028).
Approvers
Section titled “Approvers”- When users exist, a workspace’s approvers on the managed service are its
adminusers.ControlStore.approversOf(workspaceId)reads them frommembershipsandusers, and the approver ID is the user ID.- The
approverstable and its operator endpoint are retired in that change. - A workspace with no admin still answers
no_approvers.
- Self-hosted
ADMIN_EMAILSkeeps approving. Its users are admins through membership rows, so their approver ID becomes the user ID too. - The switch changes every approver ID, so links minted before it answer
approver_removed. Pending approvals are requested again after the switch, which mails new links. Nothing is deployed with real approvals yet. - Approval stays by the mailed link only.
- The dashboard shows a pending approval’s status and content (
sendApprovals.get). - It can mail the links again by repeating
workflows.activate. - It never approves, and there is no
apiaction that approves (ADR 0033).
- The dashboard shows a pending approval’s status and content (
Amendment (2026-11-18, ADR 0044): decided by the maintainer, approvers are mailed only in workspaces whose sendApprovalRequired setting is on; it is off by default. Proposed in ADR 0044, not decided: workspaces.setSendApproval is a user-only workspace action with role admin, so only an admin’s session changes the setting, and no project key or MCP grant can. ADR 0044’s other new actions are project actions with principal: "any".
Amendment (2026-11-19, built with the first workspace actions): workspaces.get is a user-only workspace action with role member, at GET /api/workspace. The path is singular because the Customer-Lite-Workspace header, not the path, names the workspace; later header-selected resources follow the same convention. workspaces.create accepts an optional idempotencyKey, unique per creator, and a repeated key returns the workspace the first call created.
Amendment (2026-11-19, built with member management): members.list (role member) and members.add, members.setRole, and members.remove (role admin) are user-only workspace actions under /api/workspace/members. members.list shows every member’s address and role to every member of the workspace. members.add adds only a user who has already signed in, by the address they sign in with, and sends no mail; an address no user has signed in with answers not_found, and adding a member again with the same role returns them (with another role, conflict). An admin may demote or remove themselves, unless they are the last admin, which answers conflict. A member cannot leave a workspace by themselves yet; an admin removes them. Each write checks again, in its own statement, that the caller is still an admin, so an admin demoted or removed while a request is in flight cannot act once more (forbidden). A removal is POST …/:userId/remove, not DELETE, because ADR 0040’s CSRF rule requires a JSON body on every session write, and a body on DELETE is not dependable across clients and proxies; later removals of a sub-resource use POST /…/:id/<verb> too.
Amendment (2026-11-19, the gate on adding members directly): direct adding needs no consent from the user added, and tells a workspace’s admins whether an address has signed in. It is therefore enforced, not only documented: while anyone may sign in (SIGN_IN_OPEN=true on the managed service), members.add answers forbidden before it reads anything, and names invitations. Invitations, which the invitee accepts, replace it with the dashboard’s members page, before sign-in opens to anyone and before the managed service mails admins as approvers, so that adding a user cannot make the system mail them. The residual risk is accepted: while sign-in lets in only listed addresses (ALLOWED_EMAILS, and ADMIN_EMAILS on a self-hosted installation), those users, whom the operator trusts, can still find whether another of them has signed in, and add them, until invitations exist.
Amendment (2026-11-19, workspaces.create replays): a repeated key is looked up by its creator and key alone, without the creator’s membership. It returns the first workspace only for the same name, and while the creator is still a member of it; otherwise it answers conflict, which names no workspace. Before this, a replay with another name returned the first workspace (200), and a replay by a removed creator answered workspace_limit_reached. The name is compared with the workspace’s current name, which is the first call’s while no action renames a workspace; an action that renames one must store what the key was first sent with. A removed creator’s workspace still counts against MAX_WORKSPACES_PER_USER, which counts workspaces.created_by as decided above.
Amendment (2026-11-20, built with the installation admins’ memberships): an installation admin is a user who signed in with a verified address that ADMIN_EMAILS lists, so they exist only on a self-hosted installation; the cloud mode refuses the variable. Their rows are written in two places. workspaces.create writes them in the same batch as the workspace. Each sign-in of an installation admin, ADR 0040’s bootstrap included, makes them admin of every workspace before their session is written: it adds the memberships they lack and promotes a member one. That one step covers a user’s creation, an address added to the list later, and the workspaces created before this change, with nothing for the operator to run. A user who stays signed in gets the rows at their next sign-in, so the operator signs out and in again to have them at once. With the undo below, these are the only writes that span workspaces. They never remove or demote, so the last-admin rule holds. “Every workspace” includes those made by the operator before users existed. While an address is listed, members.setRole and members.remove refuse to demote or remove its user with conflict, which names ADMIN_EMAILS, checked in the same conditional statement as the write: the invariant above holds at write time instead of being undone at the next sign-in. An address removed from the list keeps its rows, which become ordinary memberships that the workspace’s admins manage. To take an address’s access away, the operator removes it from both ADMIN_EMAILS and ALLOWED_EMAILS. If its user was a workspace’s only admin, the operator recovers the workspace by listing another address, whose user is admin of every workspace at their next sign-in. The rows carry no source column: whether a row’s user is an installation admin is read from the current list at each write, which is all the refusal needs, and the source of an earlier row matters only to a bulk removal, which is open. Deriving the memberships from the variable instead of writing rows would contradict this ADR’s real membership rows and is not done. If the bootstrap route removes its user because the session failed, it first undoes the sign-in step’s rows, keeping any that is the only admin of a workspace with other members.
Amendment (2026-11-20, built with the projects): projects.create and projects.list are at POST and GET /api/workspace/projects, under the workspace the Customer-Lite-Workspace header selects. A project has an ID and a creation time, and no name yet: with one project per workspace, the workspace’s name names it. projects.create checks again, in the same conditional statement as the one-project rule, that the caller is still an admin (forbidden), so concurrent calls create at most one project, and the admin check holds at write time. It accepts an optional idempotencyKey, unique per workspace: a replay by any admin of the workspace returns the project the key created, and a replay after a project was made without that key answers conflict. The new project’s store receives the workspace’s sender setup (ADR 0035), so a project created after its workspace’s domains were verified can send. Every call by a confirmed admin replicates again, a replay and a conflict included, and a replication that does not reach the new project answers an internal error. An internal error may therefore leave the project created; a retry finishes it, with the same key (which returns the project) or without one (which answers conflict once the copy is written). The action’s description says so. Interim: when ADR 0039’s replicate job exists, projects.create writes that job in the same batch as the insert, and this synchronous step goes away. Projects get names before the one-project rule is lifted, because ADR 0051’s consent screen picks a project. Lifting the rule also needs two follow-ups: the insert gets ON CONFLICT (workspace_id, create_idempotency_key) DO NOTHING, so a race on one key answers duplicate rather than an internal error, and replication is skipped or limited to the new project when the other stores already hold the current replica.
Amendment (2026-11-20, built with key management): apiKeys.create, apiKeys.list, and apiKeys.revoke are user-only project actions with role admin, at POST and GET /api/api-keys and POST /api/api-keys/:id/revoke, for the project the Customer-Lite-Project header selects. TARGET_RULES now allows user on a project action for them. apiKeys.list is admin too, as the table above says, so members do not see a project’s keys. Only secret keys (cl_sk_) are created; restricted and publishable keys, expiry, rotation with overlap, and the last-used time of ADR 0026 are not built yet.
- Stored IDs. Keys get a stored ID (
key_and 32 hex characters), whichapiKeys.listshows,apiKeys.revoketakes, andcore/authreturns as the key’s identity. That identity is what a send confirmation binds (ADR 0050) and what the dashboard names a key by. It replacesderiveId("key", keyHash), so the ID no longer depends on the hash.0008_api_key_managementrebuildsapi_keyswithidNOT NULL and gives each existing key a random ID. A token previewed by such a key before the migration then answersconfirmation_invalid, with a fresh token, once. The migration also addscreated_byandcreate_idempotency_key. - The plaintext is in the creating response only. It is
cl_sk_and 256 random bits. Only its SHA-256 and its prefix and last four characters are stored, and every other response shows that redacted form. No log line carries it. - Retries.
apiKeys.createtakes an optionalidempotencyKey, unique per project. The plaintext cannot be shown again, so a replay answersconflictand names the key the first call created, which the caller revokes if the plaintext was lost. - Write-time checks. Each create and revoke checks again, in the statement that writes, that the caller is still an admin of the project’s workspace, as the member writes above do. A demoted admin cannot mint a key that outlives their role.
- Revocation takes effect on the next request. The key lookup reads
revoked_aton every request, and there is no lookup cache yet; when ADR 0026’s short-TTL cache is built, revocation must clear it. Revoking a revoked key returns it unchanged. An ID that names no key of the selected project answersnot_found, so another project’s key is never revealed. Revocation stops the key, not what it already started: a send approval a key’s call requested, and the approval linkSEND_APPROVAL_DELIVERY=responsereturned to it, stay decidable until they expire, since a person decides them by the link (ADR 0033). A send confirmation token the key previewed is refused, because confirming needs the key. Expiring a revoked key’s pending approvals and links on revoke is a follow-up.
Consequences
Section titled “Consequences”- This resolves the open item “workspace-level actions do not fit the
ProjectScopecontract”, with theworkspaceandactortargets. - The isolation fixture also runs every action as a session, with a user who is a member of workspace A only:
- every project or workspace action naming a tenant of workspace B answers
not_found; - naming the other project of A works only with a membership in A.
- every project or workspace action naming a tenant of workspace B answers
surfaces/httpgains session authentication (with the CSRF rule of ADR 0040) and the two headers. The REST and MCP authentication seams converge on onecore/authentry that returns the principal, as the MCP open item asks.- Invitations, member management, and their audit log entries come with the dashboard’s members page.
- With one project per workspace, the per-project daily approval-mail cap of ADR 0033 is also a per-workspace cap for now.
- This amends eight ADRs, each with an amendment line:
- ADR 0013: plan-limit notices go to the workspace’s admins;
- ADR 0016: the recipient-cap notice goes to the workspace’s admins;
- ADR 0019: handlers may also receive a
WorkspaceScopeor anActorScope, andauthbecomesprincipal; - ADR 0026: the workspace roles are
adminandmember, and the owner’s powers areadmin’s; - ADR 0033: approvers are the workspace’s admins, from memberships, and the
approverstable is retired; - ADR 0039: the key-and-grant reach of its actions follows the table above, and the role they need is
admin, notowner; - ADR 0040:
ADMIN_EMAILSusers are admins, and its last-owner rule is the last-admin rule; - ADR 0044:
workspaces.setSendApprovalneeds an admin’s session.
- Amendment lines in ADR 0026 and ADR 0031 record the MCP exposure of
user-only actions, written while this ADR was Proposed.
Amendment (2026-11-20, pending ADR 0051, Proposed): an MCP grant is the oauth_grant credential of the user principal, accepted only by any actions, so workspace-level and user-only actions stay session-only.