Workspaces

"Workspace" is the UI term for an Organization. It represents the tenant boundary where data, billing, and members reside.

Workspace Types

In "Team" mode, there are two types of workspaces:

Personal Workspaces

• Automatically created during signup.
• Owned by the user.
• Tagged with isPersonal: true in the organization_profiles table.
• Default name: [First Name]'s Workspace

Team Workspaces

• Created manually by users.
• Intended for collaboration.
• Tagged with isPersonal: false.

Creating Workspaces

Workspaces are created using the createWorkspace mutation in packages/backend/convex/organizations/mutations.ts.

This mutation:

1. Calls the Better Auth API to create the organization.
2. Creates an organization_profiles record to track its lifecycle.
3. Automatically sets it as the user's active organization.

Note: Workspace creation is disabled when organizationConfig.mode is set to "personal".

Switching Workspaces

The workspace switcher in the app sidebar calls the setActiveOrganization mutation.

Switching contexts requires updating:

1. Convex: Updates users.activeOrganizationId in the database.
2. Better Auth: Updates the active organization on the session cookie.

This dual-update ensures that server actions, React Server Components (which rely on the session cookie), and Convex functions (which rely on the database) all see the same active workspace.

Deleting Workspaces

Only Owners can delete a workspace. Deletion is handled by the deleteOrganization mutation.

This is a Level 4 sensitive action, meaning:

• It requires step-up verification (password, email code, or TOTP).
• It consumes a single-use verification grant.
• It cannot be performed on a fresh session alone.

When deleted:

1. The organization_profiles status changes to deleted.
2. The cleanupOrganizationBilling helper cancels active subscriptions.
3. Users with this workspace active fall back to their personal workspace.

Next Reads

• Switching to Personal Mode — disabling team workspaces.
• Security Model — sensitive action verification.