Organizations

Why organizations?

Many apps need to group users into workspaces or teams (“organizations”) so they can share access to data and settings. Organizations let you:

  • Share resources between multiple members under a single org.
  • Invite teammates by email and control membership.
  • Switch between personal and team workspaces.

Prerequisites

  • sendEmails: true in src/convex/auth.constants.ts (required for invites). See Sending Emails.

Activate organizations

src/convex/auth.constants.ts

Add the switcher to your layout

Embed the OrganizationSwitcher in your root app layout so users can switch workspaces anywhere in the app.

src/routes/+layout.svelte

Features

Organizations are enabled when organizations: true is set and the OrganizationSwitcher is present in your root layout. Because invites are email‑based, ensure sendEmails: true and your email provider are configured.

URL updates when switching organizations

If a user is on a page like /my-org/products and switches the active org with the OrganizationSwitcher, the URL is automatically rewritten to /another-org/products.

/active-organization shorthand

Calling /active-organization redirects to the user’s current active organization.

  • /active-organization → /umbrella-company
  • /foo/active-organization/bar → /foo/umbrella-company/bar

This is useful in support docs or onboarding to provide org‑aware deep links.

Checking user roles

The useRoles helper provides reactive access to a user’s role within an organization. It returns computed properties that check the user’s permissions.

Basic usage

Check the current user’s role in the active organization:

Check role in a specific organization

Pass an orgId to check the user’s role in a different organization:

Reactive organization changes

Use $derived to reactively update role checks when the organization changes:

Available properties

The useRoles helper returns an object with the following reactive properties:

  • hasOwnerRole — true if the user is an owner
  • hasAdminRole — true if the user is an admin
  • hasOwnerOrAdminRole — true if the user is either an owner or admin
  • isMember — true if the user has any role (is a member of the org)
  • role — the raw role value ('owner', 'admin', 'member', or undefined)

Options

The useRoles function accepts an optional configuration object: