Workspaces and Organizations

SupaCloud uses one term for one meaning across the database, API, and UI. The word team used to be overloaded; it is now reserved for the agent domain only.

The hierarchy

• Organization — the top tenant. It owns billing/seats, SSO, and invitations. Every user belongs to exactly one organization. A personal organization is auto-provisioned on signup.
• Workspace — the resource container under an organization. Projects, tasks, runs, workflows, schedules, secrets, and connectors all live in a workspace. Membership is by user.
• Project / Task / Run / Workflow / Connector — resources inside a workspace.

The server derives the active organization from the active workspace — there is no organization switcher.

Sharing a link across workspaces

Because every resource lives in a workspace, a link like /tasks/{id} is only half an address: it names the object but not the tenant it belongs to. The missing half used to be filled in silently from whichever workspace the recipient happened to have open — so a colleague opening a shared task link from a different active workspace saw a “not found” page even though their membership and permissions were fine.

Two things resolve it now, and the difference between them is the point:

• Links SupaCloud sends carry their workspace. Chat digests, notifications and search results append the workspace to the link, so the recipient lands in the right place without doing anything.
• A link that does not carry one is resolved by membership. If you open an unqualified link to something in another of your workspaces, the page offers to switch: This is in another workspace — Switch to X / Stay here. It is an offer, not a jump, because switching reloads the page and would discard unsaved work.

Why it is an offer and not an answer

That switch prompt appears only when you really are a member of the workspace that holds the resource. For everyone else the response is the plain “not found” the resource itself gives — byte for byte the same answer an id that never existed gets. Otherwise the friendlier message would itself be the leak: it would confirm that someone else’s task, run or project exists. Membership is checked as part of the same database query that looks the resource up, so an answer about a workspace you are not in cannot be produced at all.

One active workspace, everywhere

Your active workspace is a property of you, not of the window you happen to be looking at. Switching it in the web switcher, in the web terminal, in Telegram or in Discord switches it in all of them, and on your other devices too — the choice lives on the server.

That matters most where it used to hurt: a chat workspace switch could previously look like it worked while changing nothing, because the choice was stored against a Telegram chat. Someone who had never linked Telegram — or who worked from Discord — had nowhere for it to be written. Two people could then be looking at the same screen name and acting in different workspaces without either of them seeing a mistake.

Two deliberate exceptions:

• A ?ws= link is a per-navigation detour, not a decision. Opening a link that carries a workspace shows you that workspace without moving your saved choice. Close the tab and you are back where you were.
• You can only activate a workspace you are a member of. The check runs on the server, on every surface, and a refusal changes nothing — so a rejected attempt cannot leave a stale pointer behind. Losing access to a workspace you had active simply falls back to your own default; the stale preference is never honoured.

Why not “team”?

Team and Teammates are reserved for the agent domain — a multi-agent group spawned for one task. The tenant is always a Workspace; the top tenant is always an Organization.

Ubiquitous-language rule

Never use “team” for the tenant. This rule is enforced in CI by an architecture test (no new team_id tenant column) and a frontend i18n-lint rule (no new user-facing “Team” string outside the agent and delivery-board namespaces).

Entitlements

What a workspace can do is resolved by first-non-null priority: user override → seat type → workspace override → organization plan → default, composed under the deployment edition. A seat can never grant an edition-gated feature.

This vocabulary is the subject of ADR 0040 and the organization tenancy model is ADR 0035.