Skip to content

0041. Users, workspace memberships, and the user principal of API actions

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.

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 on user_id, and role one of admin, 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 memberships
    WHERE workspace_id = ?1 AND user_id = ?2
    AND (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.

  • workspaces gains name and created_by. api_keys gains created_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 owner role, decided by the maintainer on 2026-11-19. ADR 0026’s owner powers belong to admin. 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.setSendApproval among them), and managing memberships are principal: "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 is sendingDomains.add, sendingDomains.verify, and sendingDomains.remove, which stay principal: "any" as ADR 0039 decides, because no action sets verified; only SES does, after the domain’s DNS proves control. Dropping owner therefore gives keys and grants, as a category, no reach they did not have. Within a team, though, the users whose grant with scope admin can 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_by names the user who created it.

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.

ApiAction gains three fields, and principal replaces auth: "api_key":

  • principal: "project_key" | "user" | "any": who may call it. user means a session. any accepts a key, a session, or a grant. Any other caller gets forbidden.
  • target: "project" | "workspace" | "actor": what the handler acts on.
    • project handlers receive a ProjectScope, as today.
    • workspace handlers receive a WorkspaceScope.
    • actor handlers receive an ActorScope, 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. scope stays 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.list and sendingDomains.get (scope: read, role member) are open to a project key.
  • sendingDomains.add, sendingDomains.verify, and sendingDomains.remove (scope: admin, role admin) need an admin’s session, or a grant with admin held by an admin.
  • Inputs never carry a project or workspace ID (ADR 0019). A session names its tenant in a header:
    • Customer-Lite-Project: <projectId> for project actions;
    • Customer-Lite-Workspace: <workspaceId> for workspace actions.
  • core/auth, the only minter of scopes, resolves it in order: the project through ControlStore (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.
  • 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.
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_USER workspaces (configuration, default 3), counted by workspaces.created_by, so the memberships of ADMIN_EMAILS admins do not count. The count and the insert are one conditional statement, and over the cap workspaces.create answers workspace_limit_reached (422), a new error code.
  • One project per workspace until suppression is replicated across a workspace’s projects: projects.create on a workspace that has a project answers conflict. 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: member for reading, editing data, drafts, and test runs; admin for activating and stopping workflows.
  • Key management, workspaces, projects, and later memberships and invitations are user only. No key and no grant can create a key, a workspace, or a project.
  • An ADMIN_EMAILS user is admin of 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.
  • 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 answers forbidden on 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 every user-only action.
  • The dashboard calls the same api actions with its session cookie and the header (ADR 0028).
  • When users exist, a workspace’s approvers on the managed service are its admin users.
    • ControlStore.approversOf(workspaceId) reads them from memberships and users, and the approver ID is the user ID.
    • The approvers table and its operator endpoint are retired in that change.
    • A workspace with no admin still answers no_approvers.
  • Self-hosted ADMIN_EMAILS keeps 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 api action that approves (ADR 0033).

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), which apiKeys.list shows, apiKeys.revoke takes, and core/auth returns as the key’s identity. That identity is what a send confirmation binds (ADR 0050) and what the dashboard names a key by. It replaces deriveId("key", keyHash), so the ID no longer depends on the hash. 0008_api_key_management rebuilds api_keys with id NOT NULL and gives each existing key a random ID. A token previewed by such a key before the migration then answers confirmation_invalid, with a fresh token, once. The migration also adds created_by and create_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.create takes an optional idempotencyKey, unique per project. The plaintext cannot be shown again, so a replay answers conflict and 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_at on 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 answers not_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 link SEND_APPROVAL_DELIVERY=response returned 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.
  • This resolves the open item “workspace-level actions do not fit the ProjectScope contract”, with the workspace and actor targets.
  • 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.
  • surfaces/http gains session authentication (with the CSRF rule of ADR 0040) and the two headers. The REST and MCP authentication seams converge on one core/auth entry 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 WorkspaceScope or an ActorScope, and auth becomes principal;
    • ADR 0026: the workspace roles are admin and member, and the owner’s powers are admin’s;
    • ADR 0033: approvers are the workspace’s admins, from memberships, and the approvers table is retired;
    • ADR 0039: the key-and-grant reach of its actions follows the table above, and the role they need is admin, not owner;
    • ADR 0040: ADMIN_EMAILS users are admins, and its last-owner rule is the last-admin rule;
    • ADR 0044: workspaces.setSendApproval needs 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.