Organizations & invitations

Every user has a personal workspace from the moment they sign up, and can also belong to shared organizations. If your app is used by individuals, you never have to think about any of this: the org UI stays hidden until someone actually belongs to a shared organization.

Personal workspaces

A personal workspace is created automatically at signup, owned by that user. It exists so there is always somewhere for data to live, which is what lets a single-user install behave exactly like a normal single-tenant app.

Two things follow from that:

• It can't be deleted. It's the fallback every user resolves to.
• It's invisible when it's the only one you have. No switcher in the header, no org name on screen — the app looks exactly like a single-user app until you actually have a team.

Creating an organization

Go to Settings → Organization and give it a name. You become its owner, and the switcher appears in the header once you belong to more than just your personal workspace.

Creation lives in Settings rather than the header switcher on purpose: a solo user should not see org chrome in the app shell at all, and Settings is where you'd go looking for it.

Switching between organizations

The switcher sits in the header next to the app name, showing whichever organization you're currently working in. Pick another and the page re-scopes immediately — items, webhooks, API keys and everything else org-scoped now belong to that organization. You can also switch from the command palette (⌘K / Ctrl+K) by typing the organization's name.

Your choice is remembered per device. Reloading the page, closing the tab, and coming back tomorrow all keep you where you left off. But signing in on your phone starts you on your default organization rather than inheriting whatever your laptop was on — which means you can work in two organizations at once on two devices.

You only ever see one organization's data at a time. There's no "all organizations" view. That's deliberate: it means every screen in the app has exactly one answer to "whose data is this", and no query can accidentally mix tenants.

Managing an organization

Settings → Organization is where owners and admins manage the org itself:

• Rename it.
• See who's in it — everyone's name, email, role, and when they joined.
• Change someone's role between member, admin and owner.
• Remove someone, after a confirmation step.
• Delete the organization, if you're an owner. This is permanent and takes its data with it.

What you can do depends on your role — see Org roles for the full ladder. Two rules catch people out, and both are enforced by the server rather than just hidden in the UI: an admin can't promote anyone to owner (you can't grant a role above your own), and the last owner can't be removed or demoted — promote someone else to owner first. If you try, you'll get told exactly that rather than a generic error.

Inviting teammates

Owners and admins invite by email from Settings → Organization. Enter the address, pick a role, and send. The invitation appears in the pending list until it's accepted, declined, revoked, or expires.

Invitations expire after 7 days by default. Set ORG_INVITE_EXPIRES_DAYS to change it.

From the pending list you can:

• Resend — sends the email again and extends the deadline. The link already in the recipient's inbox keeps working; it does not mint a second invitation.
• Revoke — invalidates the invitation immediately. Any link already sent stops working.

Re-inviting an address that already has a pending invitation replaces the old one, so there is never more than one live invitation per seat.

What the recipient sees

They get an email and click through to an accept page. What happens next depends on their state:

They already have an account. They see the organization name and who invited them, then Accept or Decline. Accepting drops them straight into that organization — not their personal workspace — because that's what they clicked the email to do.

They don't have an account yet. They're sent to sign up first and returned to the invitation automatically afterwards, so the invite isn't lost in the round-trip.

They're signed in as somebody else. The page says so and offers to switch accounts. An invitation can only be accepted by the address it was sent to.

Their email isn't verified yet. They're asked to verify first, with a button to resend the verification email. This matters more than it sounds: it's what stops someone registering your email address and claiming an invitation meant for you. Verification proves the account really owns the mailbox the invitation was sent to.

The invitation is expired, already used, or revoked. They're told it's no longer valid and to ask for a new one. All three look identical from the outside, deliberately — see below.

A note on privacy

Invitation links can only be inspected by the person they were sent to, and only after they sign in. To anyone else — including someone guessing invitation IDs — an invitation that doesn't exist, one that's expired, and one that's already been used are indistinguishable. That's on purpose: telling them apart would confirm which addresses have been invited to what.

Roles

An organization always keeps at least one owner — the last one can't be removed or demoted until somebody else is promoted.