Three gates on your own routes, a selection a session acts in, and the routes the capability ships for everything else. {base} below is the configured basePath, /organizations by default. Every route the capability ships is in the reference.
Gate your own routes
Compose the gates on the route line, in this order: who is signed in, which membership is in force, and whether its role holds the power.
import type { D1Database } from "@cloudflare/workers-types";
import { requireAuth } from "@pithy-sh/auth/src/http/middleware";
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
import { validate } from "@pithy-sh/core/src/http/validation";
import { organizationDatabase } from "@pithy-sh/organization/src/data/tables";
import { requireOrganization, requirePower } from "@pithy-sh/organization/src/http/guard";
import { roles } from "./organization/roles";
const deps = {
catalog: roles,
database: (env: Record<string, unknown>) => organizationDatabase(env.DB as D1Database),
};
app.get(
"/coaches",
describeRoute({ summary: "List the coaches.", verification: ["bearer", "session"], responses: { 200: CoachList } }),
requireAuth(),
requireOrganization(deps), // fills c.var.acting, or 404s
requirePower("sessions:read", deps), // asks the matrix, or 403s
validate("query", ListCoaches),
handler,
);c.var.acting exists only downstream of requireOrganization(), and it is non-optional there, so a handler reads it without a null check:
{ organizationId, slug, name, userId, role, chosen }role narrows to the union your catalog declared, and requirePower refuses a power nobody declared at compile time rather than denying everyone at runtime. chosen says whether somebody picked this account; nothing authorizes on it.
A 404 and a 403 mean different things here. requireOrganization() answers organization/not_found (404) for a caller with no membership in force, and for one naming an account they are not in — the same bytes as an account that does not exist. requirePower() answers organization/forbidden (403), because by then the caller has been proved a member and already knows the account exists. A proved member of an account an operator has suspended gets organization/organization_suspended (403) from requireOrganization() instead, and a deleted account is the 404; organization lifecycle has both.
Then scope your own queries. This capability cannot see your tables. Every query against a tenanted table of yours should join memberships on both halves of c.var.acting — the user and the organization — so no arrangement of callers reaches another tenant’s rows. The package’s docs/scoping-your-own-tables.md has the pattern and the test that proves it.
Choose the organization in force
The organization in force is session state, never a path segment. A URL that cannot name another tenant cannot be pointed at one.
GET {base}lists every organization the caller may act in, ordered by name, each with their role. Beside the list it answersacting— the id in force, ornull—chosen, andsuspended, how many of the caller’s organizations are suspended and so left off the list.POST {base}/actingwith{ organizationId }proves a membership and writes the selection, keyed by the session. An account the caller is not in is the same 404 as one that does not exist.
Until a session has chosen, every {base}/current route and every route behind requireOrganization() answers 404 with No organization is in force. The action says choose an organization when the caller belongs somewhere, and join or create one when they belong nowhere, so a client can tell those two apart without either naming an account.
The selection is a preference; the membership is the authority. Every request re-joins memberships, so a selection whose membership has been deleted grants nothing and reads as no selection.
A bearer client keeps its selection across a rotation. Its session token is replaced each time it rotates, and the selection moves to the new session for the same user, with no wiring: Add Organization has why.
Founding one does not move it. POST {base} creates an organization with the caller as its first member, at the first role in your catalog that administers and may be assigned, and leaves the selection where it was. Creating a second account from a settings pane must not move somebody out of the one they were working in. slug is optional; omitted, it is derived from the name. allowSelfService: false refuses the route for every caller, and slugs: "derived" refuses a supplied slug.
An idempotencyKey makes a retry safe. A client that lost the answer to a founding cannot tell whether it landed, and names are not unique, so a retry without a key founds a second organization. Send a key the client chooses once per organization, 1 to 200 characters. The first request founds and answers 201. A repeat by the same person with the same key, name and slug answers 200 with the organization the key founded, read as it is now, and writes nothing: no second audit event, and onCreate and onJoin do not run. The same key with a different name or slug refuses with organization/idempotency_key_reused (409). Two concurrent requests with one key found one organization, and the loser answers 200 with it. Keys are per person: somebody else’s identical key founds their own. A repeat for an organization that is deleted or suspended answers as every other door does, organization/not_found or organization/organization_suspended. The key is freed when the purge erases the organization, and the same key then founds a new one. An owner’s DELETE {base}/current and an operator’s hard deletion start that purge at once; after a soft deletion it waits for the window to close. Until then a repeat answers the 404.
Run the roster
| Route | Power | What it does |
|---|---|---|
GET {base}/current/members | organization:read | The roster, oldest first, with names and addresses resolved through auth’s published reader |
PATCH {base}/current/members/:membershipId | organization:manage | Change a role, to one the catalog lets anybody assign |
DELETE {base}/current/members/:membershipId | organization:manage | Remove somebody, and clear their selection of the account |
POST {base}/current/members/leave | — | Leave. A different act from being removed, and recorded as one |
Minting an administrator takes a second power. Handing somebody a role that holds your administrativePower — by a role change or by an invitation — also needs members:manage. Running the roster day to day does not.
The account always keeps somebody who can administer it. The last holder of administrativePower cannot be demoted, removed or leave; each answers organization/last_administrator (409). Nobody can take away their own administration either.
A role nobody may assign does not change here. Somebody holding an unassignable role cannot be demoted, removed or leave through these routes, and nobody can be given one. In the starter catalog that is owner: an owner who wants out hands the account on first.
Invite somebody
POST {base}/current/invitations with { email, role } makes an offer, under organization:manage. The role has to be assignable, and an administering one needs members:manage too. Inviting an address that already holds a live offer supersedes it, so there is one live link per address. An offer lasts invitationTtlDays, 14 by default.
With sendInvitationEmail on, the link is mailed and the response’s acceptUrl is null. With it off, nothing is mailed and acceptUrl carries the link for your own code to deliver. GET {base}/current/invitations lists the outstanding offers, POST …/:invitationId/resend mints a fresh link and kills the old one, and DELETE …/:invitationId withdraws one.
The link goes to your app, not to this capability. It is baseUrl plus invitationAcceptPath plus the token, so the page you serve is /invitations/:token by default. That page makes two calls:
GET {base}/invitations/:tokenis public and grants nothing. It answers what the offer is —organizationName,inviterName,role,expiresAt— for the screen to show.POST {base}/invitations/acceptwith{ token }, from a signed-in session, redeems it.
readInvitation(token) and acceptInvitation(token) in @pithy-sh/organization/src/client/api make the two calls, and the --organization screens of pithy ui add react and pithy ui add react-native include the page. Accepting does not move the organization in force: call chooseOrganization with the organizationId the accept answers if the reader should act in it. A client off the Worker’s origin, a native app, passes origin and a fetch that adds its bearer credential.
Accepting needs a session whose own address is the invited one. That is the property that makes a forwarded link useless. Every way an offer cannot be redeemed — no such token, used, withdrawn, expired, a role the catalog no longer assigns, the wrong address, an account suspended or deleted — is one answer, organization/invitation_invalid (400), so nobody holding a forwarded link learns which it was.
Redeeming twice is not an error: the second answers joined: false with the membership already held. Accepting does not move the acting selection either. An account at its seat limit refuses the join with organization/seat_limit_reached, and the offer stays pending until a seat frees.
Transfer ownership
These routes mount only where you passed an ownership pair. The role it confers is unassignable, so nothing but this transfer — or an operator — can give it to anybody.
- Offer.
POST {base}/current/ownershipwith{ membershipId }. While somebody holds the account, only they may offer it. While nobody does — the ordinary state of a young account — somebody who administers it may volunteer themselves, and may appoint nobody else. - Accept. The nominee calls
POST {base}/ownership/accept. That is the transfer: the previous holders are demoted todemotesTo, the nominee takesconfers, and the offer is spent, in one write.
GET {base}/current/ownership reads the standing offer for any member, so the nominee can see it. DELETE {base}/current/ownership withdraws it: the holder may, or, in an account nobody holds, the person who volunteered. One account offers itself to one person at a time, so offering again replaces the offer, and an offer lasts nominationTtlDays, 7 by default.
No offer, an expired one, one whose nominee left, and one made to somebody else all answer organization/nomination_invalid (400), the same sentence.
An account whose owner has gone is stuck on this surface, deliberately. No route a member can reach repairs it. An operator can, through membership administration, under its own scope and with a reason.
Rename it, mark it, end it
PATCH {base}/current renames the account or sets its mark, under organization:manage. A mark is a stored data: image, never a remote URL, and null takes it off. The short name does not change here; only an operator moves it.
DELETE {base}/current, under organization:delete, deletes the account through the organization lifecycle, as a hard deletion with the owner as its actor. It is shut at once: refused to every member, gone from every list, every selection of it cleared. Then the purge erases it from every capability that declares an organization purge contribution, stored files and media included: its memberships, invitations, offers, founding records and selections go in organization’s own last step, with your own tenanted rows when you hand them over:
organization({
roles,
onDelete: (d1, organizationId) => [
myDatabase(d1).deleteFrom("projects").where("organizationId", "=", organizationId),
],
}),Return statements rather than doing the work. They run when the purge erases the account, not inside the request: in the same d1.batch as the capability’s own deletes, ahead of them, so a failure rolls that step back and the Workflow retries it. Work that is not a statement, such as revoking a third-party connection or telling every member, belongs in an organization purge contribution on your app capability, which runs as its own step and is handed who deleted the account and why.
The body is optional. { reason } follows an operator’s rules, at most 500 characters and no email address, and is recorded on the history row and the organization/deleted audit event and handed to every purge contribution. With no reason, or no body at all, Deleted by its owner. is recorded. The response is { organizationId, deletedAt, purge }: purge is started, or pending when this Worker binds no purge Workflow or the start failed, and the daily pass starts it then. onOrganizationDeleted fires, and onOrganizationPurged once the purge finishes.
Nobody’s account goes with it unless you say so. ownerDelete: { members: "sole" } in the config also deletes, hard and through auth’s own lifecycle, the accounts of the members whose only organization this is, and the response then carries members, saying who was reached and who was skipped. The owner’s own account is never touched. The default, none, deletes no account.
A route of your own can run the same deletion behind a check of its own, such as a typed name: deleteOrganizationAsOwner(c, { reason }) from @pithy-sh/organization. Mount requireSameOrigin() ahead of it, as the kit’s own route does. Organization lifecycle has the example.
Your own rows, in the same write
Creating has the same shape as deleting. Two more seams add your rows to the batch that founds an account or begins a membership, so a row you need from the first request exists with it or not at all. Each is handed the binding and returns statements, as onDelete does:
organization({
roles,
// Founding. After the organization and the founder's membership are inserted.
onCreate: (d1, { organizationId, membershipId, founderUserId, name }) => [
myDatabase(d1).insertInto("workspaces").values({ id: crypto.randomUUID(), organizationId, name }),
],
// Every new membership. After the membership is inserted.
onJoin: (d1, { organizationId, membershipId, userId, role, via, invitationId }) => [
myDatabase(d1).insertInto("seats").values({ membershipId, organizationId, userId }),
],
}),onCreate runs when somebody founds an account through POST {base}. Its statements go after the organization and founder-membership inserts, so they may reference both.
onJoin runs whenever a membership begins, after the membership insert, in the batch that writes it. via says how: "founded", "invitation" through POST {base}/invitations/accept, or "operator" through an operator’s add. invitationId is the accepted invitation’s id, and null otherwise. A founding is one batch: the organization, the founder’s membership, onCreate’s statements, then onJoin’s. Accepting an invitation you already hold begins nothing, so onJoin does not run.
A failing statement rolls the whole write back. A founding leaves no organization and no membership, and the route answers 500. An acceptance or an operator’s add leaves no membership, and a failed acceptance leaves the invitation pending, so its link still redeems. A derived slug that collides is retried with the same ids and the same statements, so a founding that commits writes your rows once.
What a write answers is what its batch committed. Your statements may change the rows they follow: an onCreate that makes the founder owner, or an onJoin that promotes the new member. The membership is read back after the batch, so the founding’s organization.role, the acceptance’s role and the operator’s add answer that role, organization/created, organization/member_joined and organization/admin_member_added record it, and the operator’s notice mails it. A founding reads the organization row back too, so a column onCreate changes is answered as committed. An acceptance by somebody already a member answers the role they hold, not the one offered. onJoin’s own role is the role the membership is inserted with, decided before the batch runs, so it does not see a change onCreate makes.
Your own flows pass the same functions. createOrganization from @pithy-sh/organization/src/provision/provision takes { onCreate, onJoin } as an optional last argument, and acceptInvitation from src/invite/invite and addMember from src/members/members take { onJoin }. Without it they write as before. createOrganization takes the same idempotencyKey in its input, and answers replayed: true for a repeat, which ran neither seam. The two membership hooks are a different thing: they run after a role change or a removal is written, and cannot undo it.
What the trail records
When audit is composed, every administrative act writes an organization/* event with the member who took it: founding, renaming, a new mark, deletion, every invitation and membership change, and each step of a transfer. A refusal from somebody already acting in the account — a role reaching above itself, an attempt to remove the last administrator, an offer that cannot be redeemed — is one organization/refused event with the refusal’s code in its facts. organization/not_found is never recorded, because anybody can produce it at will by naming a UUID. No event carries an address. The reference lists every code.