Skip to main content
Achromatic
Live demo
General
Organizations

Overview

Learn how organizations work in the starter kit.

Open MarkdownFull AI corpusFeedback

Organizations are a way to share data between users. Organizations can have members with different roles and permissions.

In the starter kit, organizations are handled by Better Auth and therefore you have full control over the organization management and all data is stored in the database.

Configure

Learn how to configure organizations in your application.

Use Organizations

Learn how to use organizations in your application.

Store Data

Learn how to store data for organizations.

How Organizations Work

Organizations enable multi-tenancy in your application. Users can:

  • Create organizations - Users can create their own organizations
  • Join organizations - Users can be invited to join organizations
  • Switch between organizations - Users can be members of multiple organizations
  • Have different roles - Users can have different roles in different organizations

Active Organization

The active organization is stored in the Better Auth session. The activeOrganizationId is available in session.activeOrganizationId and can be accessed using Better Auth's hooks and APIs.

This approach provides several benefits:

  1. Session-based - The active organization persists across page navigations
  2. Simple access - Use authClient.useActiveOrganization() on the client or getSession() on the server
  3. Automatic scoping - tRPC's protectedOrganizationProcedure automatically uses the active organization
  4. Consistent state - The active organization is managed by Better Auth and stays in sync

Roles

Organizations support the following roles:

  • Owner - Full control over the organization
  • Admin - Can manage members and organization settings
  • Member - Can access organization data

A user can have different roles in different organizations.

Default Permission Matrix

The shipped settings and billing flows use the following policy:

ActionOwnerAdminMemberOutsider
Delete organizationYesNoNoNo
Manage billingYesYesNoNo
Invite or revoke membersYesYesNoNo
Change rolesYesLimitedNoNo
Upload organization logoYesYesNoNo

An admin can change member and admin roles, but cannot modify an owner or assign the owner role. Application-level administrators do not automatically receive access to an organization: they must also be a member with the required organization role.

Use the shared helpers in lib/auth/organization-permissions.ts for custom organization procedures instead of inferring access from the user's global role.