Configure multi-tenant organizations, manage members and invitations, define custom roles and permissions, set up teams, and implement RBAC using Better Auth's organization plugin. Use when users need org setup, team management, member roles, access control, or the Better Auth organization plugin.
Configure multi-tenant organizations, manage members and invitations, define custom roles and permissions, set up teams, and implement RBAC using Better Auth's organization plugin. Use when users need org setup, team management, member roles, access control, or the Better Auth organization plugin.
Setup
Add organization() plugin to server config
Add organizationClient() plugin to client config
Run npx auth@latest migrate (built-in adapter) or generate + push for Drizzle/Prisma
Verify: check that organization, member, invitation tables exist in your database
import { betterAuth } from"better-auth";
import { organization } from"better-auth/plugins";
exportconst auth = betterAuth({
plugins: [
organization({
allowUserToCreateOrganization: true,
organizationLimit: 5, // Max orgs per usermembershipLimit: 100, // Max members per org
}),
],
});
const { data } = await authClient.organization.createTeam({
name: "Engineering",
});
Managing Team Members
Use addTeamMember({ teamId, userId }) (member must be in org first) and removeTeamMember({ teamId, userId }) (stays in org).
Set active team with setActiveTeam({ teamId }).
Team Limits
organization({
teams: {
maximumTeams: 20, // Max teams per orgmaximumMembersPerTeam: 50, // Max members per teamallowRemovingAllTeams: false, // Prevent removing last team
}
});
Use updateRole({ roleId, permission }) and deleteRole({ roleId }). Pre-defined roles (owner, admin, member) cannot be deleted. Roles assigned to members cannot be deleted until reassigned.
Lifecycle Hooks
Execute custom logic at various points in the organization lifecycle:
The last owner cannot be removed from an organization
The last owner cannot leave the organization
The owner role cannot be removed from the last owner
Always ensure ownership transfer before removing the current owner:
// Transfer ownership firstawait authClient.organization.updateMemberRole({
memberId: "new-owner-member-id",
role: "owner",
});
// Then the previous owner can be demoted or removed
Organization Deletion
Deleting an organization removes all associated data (members, invitations, teams). Prevent accidental deletion:
organization({
disableOrganizationDeletion: true, // Disable via config
});
