| name | organization-best-practices |
| description | 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 @better-auth/cli migrate
- Verify: check that organization, member, invitation tables exist in your database
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
organization({
allowUserToCreateOrganization: true,
organizationLimit: 5,
membershipLimit: 100,
}),
],
});
Client-Side Setup
import { createAuthClient } from "better-auth/client";
import { organizationClient } from "better-auth/client/plugins";
export const authClient = createAuthClient({
plugins: [organizationClient()],
});
Creating Organizations
The creator is automatically assigned the owner role.
const createOrg = async () => {
const { data, error } = await authClient.organization.create({
name: "My Company",
slug: "my-company",
logo: "https://example.com/logo.png",
metadata: { plan: "pro" },
});
};
Controlling Organization Creation
Restrict who can create organizations based on user attributes:
organization({
allowUserToCreateOrganization: async (user) => {
return user.emailVerified === true;
},
organizationLimit: async (user) => {
return user.plan === "premium" ? 20 : 3;
},
});
Creating Organizations on Behalf of Users
Administrators can create organizations for other users (server-side only):
await auth.api.createOrganization({
body: {
name: "Client Organization",
slug: "client-org",
userId: "user-id-who-will-be-owner",
},
});
Note: The userId parameter cannot be used alongside session headers.
Active Organizations
Stored in the session and scopes subsequent API calls. Set after user selects one.
const setActive = async (organizationId: string) => {
const { data, error } = await authClient.organization.setActive({
organizationId,
});
};
Many endpoints use the active organization when organizationId is not provided (listMembers, listInvitations, inviteMember, etc.).
Use getFullOrganization() to retrieve the active org with all members, invitations, and teams.
Members
Adding Members (Server-Side)
await auth.api.addMember({
body: {
userId: "user-id",
role: "member",
organizationId: "org-id",
},
});
For client-side member additions, use the invitation system instead.
Assigning Multiple Roles
await auth.api.addMember({
body: {
userId: "user-id",
role: ["admin", "moderator"],
organizationId: "org-id",
},
});
Removing Members
Use removeMember({ memberIdOrEmail }). The last owner cannot be removed — assign ownership to another member first.
Updating Member Roles
Use updateMemberRole({ memberId, role }).
Membership Limits
organization({
membershipLimit: async (user, organization) => {
if (organization.metadata?.plan === "enterprise") {
return 1000;
}
return 50;
},
});
Invitations
Setting Up Invitation Emails
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { sendEmail } from "./email";
export const auth = betterAuth({
plugins: [
organization({
sendInvitationEmail: async (data) => {
const { email, organization, inviter, invitation } = data;
await sendEmail({
to: email,
subject: `Join ${organization.name}`,
html: `
<p>${inviter.user.name} invited you to join ${organization.name}</p>
<a href="https://yourapp.com/accept-invite?id=${invitation.id}">
Accept Invitation
</a>
`,
});
},
}),
],
});
Sending Invitations
await authClient.organization.inviteMember({
email: "newuser@example.com",
role: "member",
});
Shareable Invitation URLs
const { data } = await authClient.organization.getInvitationURL({
email: "newuser@example.com",
role: "member",
callbackURL: "https://yourapp.com/dashboard",
});
This endpoint does not call sendInvitationEmail — handle delivery yourself.
Invitation Configuration
organization({
invitationExpiresIn: 60 * 60 * 24 * 7,
invitationLimit: 100,
cancelPendingInvitationsOnReInvite: true,
});
Roles & Permissions
Default roles: owner (full access), admin (manage members/invitations/settings), member (basic access).
Checking Permissions
const { data } = await authClient.organization.hasPermission({
permission: "member:write",
});
if (data?.hasPermission) {
}
Use checkRolePermission({ role, permissions }) for client-side UI rendering (static only). For dynamic access control, use the hasPermission endpoint.
Teams
Enabling Teams
import { organization } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
organization({
teams: {
enabled: true
}
}),
],
});
Creating Teams
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,
maximumMembersPerTeam: 50,
allowRemovingAllTeams: false,
}
});
Dynamic Access Control
Enabling Dynamic Access Control
import { organization } from "better-auth/plugins";
import { dynamicAccessControl } from "@better-auth/organization/addons";
export const auth = betterAuth({
plugins: [
organization({
dynamicAccessControl: {
enabled: true
}
}),
],
});
Creating Custom Roles
await authClient.organization.createRole({
role: "moderator",
permission: {
member: ["read"],
invitation: ["read"],
},
});
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:
organization({
hooks: {
organization: {
beforeCreate: async ({ data, user }) => {
return {
data: {
...data,
metadata: { ...data.metadata, createdBy: user.id },
},
};
},
afterCreate: async ({ organization, member }) => {
await createDefaultResources(organization.id);
},
beforeDelete: async ({ organization }) => {
await archiveOrganizationData(organization.id);
},
},
member: {
afterCreate: async ({ member, organization }) => {
await notifyAdmins(organization.id, `New member joined`);
},
},
invitation: {
afterCreate: async ({ invitation, organization, inviter }) => {
await logInvitation(invitation);
},
},
},
});
Schema Customization
Customize table names, field names, and add additional fields:
organization({
schema: {
organization: {
modelName: "workspace",
fields: {
name: "workspaceName",
},
additionalFields: {
billingId: {
type: "string",
required: false,
},
},
},
member: {
additionalFields: {
department: {
type: "string",
required: false,
},
title: {
type: "string",
required: false,
},
},
},
},
});
Security Considerations
Owner Protection
- 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:
await authClient.organization.updateMemberRole({
memberId: "new-owner-member-id",
role: "owner",
});
Organization Deletion
Deleting an organization removes all associated data (members, invitations, teams). Prevent accidental deletion:
organization({
disableOrganizationDeletion: true,
});
Or implement soft delete via hooks:
organization({
hooks: {
organization: {
beforeDelete: async ({ organization }) => {
await archiveOrganization(organization.id);
throw new Error("Organization archived, not deleted");
},
},
},
});
Invitation Security
- Invitations expire after 48 hours by default
- Only the invited email address can accept an invitation
- Pending invitations can be cancelled by organization admins
Complete Configuration Example
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { sendEmail } from "./email";
export const auth = betterAuth({
plugins: [
organization({
allowUserToCreateOrganization: true,
organizationLimit: 10,
membershipLimit: 100,
creatorRole: "owner",
defaultOrganizationIdField: "slug",
invitationExpiresIn: 60 * 60 * 24 * 7,
invitationLimit: 50,
sendInvitationEmail: async (data) => {
await sendEmail({
to: data.email,
subject: `Join ${data.organization.name}`,
html: `<a href="https://app.com/invite/${data.invitation.id}">Accept</a>`,
});
},
hooks: {
organization: {
afterCreate: async ({ organization }) => {
console.log(`Organization ${organization.name} created`);
},
},
},
}),
],
});