Organizations & Workspaces

Confluye organizes work into organizations and workspaces. An organization is the top-level account. A workspace lives inside an organization and owns essentially everything you build — workflows, schedules, credentials, tables, documents, knowledge bases, and API keys.

Workspaces

A workspace is the unit of isolation: resources belong to exactly one workspace. API keys and members are scoped to it. Session and API checks reject cross-workspace access with 403 (Cannot … for another workspace.). REST /api/v1 keys only see the workspace that owns the key.

Switch workspaces from the workspace switcher: list, search, browse, create, or invite. Switching re-scopes views without a full reload.

Create a workspace

Signed-in users can create a workspace from the switcher, POST /api/workspaces, or tRPC workspaceShell.workspaces.create. The name is required (trimmed). The creator is stored as workspace admin and organization admin (upsert; an existing org role is not overwritten).

Google first-time users without any membership get a different path: a personal org and workspace where they are Owner. See Getting Started.

GET /api/v1/workspaces returns { workspace } for the API key's workspace, or 404 "Workspace not found". It does not list every workspace you belong to.

Members and invitations

List members (active memberships plus pending invites) from Settings → General or GET /api/workspace-members?workspaceId=… (session) / GET /api/v1/workspace-members (workspace-scoped API key).

Each listed row includes role, status (active or invited), presence, and lastActiveAt.

Invite rules

Invite roles accepted by the APIs are only admin, member, and viewer (parseWorkspaceInviteRole). Anything else — including owner — returns 400 "Member role must be admin, member, or viewer." An omitted role defaults to member.

Who may invite:

v1 also requires a workspace-scoped key. Personal or copilot keys get 403 "A workspace API key is required." Non-admin v1 invites get 403 "Admin or Owner workspace role is required to invite members."

Behavior:

1. Email is trimmed and lowercased. Invalid emails: 400 "A valid invite email is required."
2. If a user with that email already exists, Confluye upserts workspace membership at the invited role and creates organization membership as member if missing (update: {} — existing org role is kept). A leftover pending invite for that email is deleted. Audit: workspace.member.add.
3. Otherwise a workspaceInvite is upserted (status: pending). Re-inviting the same email updates the role and clears acceptedAt. Audit: workspace.invite.create.
4. Confluye then sends the invitation email. If SMTP fails, the member or invite already exists; the API still returns 400 "Invitation email could not be delivered. Check the email configuration and try again." Audit: workspace.invite.delivery_failed.

Google sign-in accepts every pending invite for that verified email (case-insensitive), in createdAt order, then skips personal-workspace creation if any workspace membership exists. Workspace roles come from the invite (normalizeWorkspaceMembershipRole: unknown values become viewer; owner is honored only if it was already stored on the invite row). New organization membership from those accepts is member; a stronger existing org role (admin/owner) is kept.

Session routes cannot list or invite members for a workspace you do not belong to (403).

Role capabilities: Roles and permissions.

Organization structure

Organizations group workspaces. Enterprise customers can also create projects (a grouping layer with organizationId + unique slug) from Settings → Environments. See Enterprise.

Organization membership can be fanned out to every workspace in the organization (syncOrganizationWorkspaceAccess). Removing an org member deletes their workspace memberships in that organization.

Organization creation and deletion are not self-serve (allowUserToCreateOrganization: false, disableOrganizationDeletion: true). The platform bootstrap and Google personal-org provisioning are the automated create paths.

Organization-level identity (SSO/SCIM) is configured once and applies across the organization.

Next steps