Organization Best Practices

What Is This?

Overview

Organization Best Practices covers the configuration and management of multi-tenant organization structures using Better Auth's organization plugin. This skill addresses how to set up organizations, manage member lifecycles, define granular role-based access control, and structure teams within a single application instance. It provides a systematic approach to handling the complexity that arises when multiple independent groups of users share the same platform.

Better Auth's organization plugin integrates directly into your authentication layer, meaning access control decisions are made at the identity level rather than bolted on as an afterthought. This tight coupling reduces the surface area for permission-related bugs and simplifies the mental model for developers building multi-tenant systems.

The skill covers the full lifecycle of organizational management: initial plugin setup, database migration, invitation workflows, custom role definitions, team segmentation, and role-based access control (RBAC) enforcement. Whether you are building a SaaS product, an internal tooling platform, or a collaborative workspace application, these practices provide a reliable foundation.

Who Should Use This

• Backend developers building multi-tenant SaaS applications who need to manage isolated user groups within a shared codebase
• Full-stack engineers integrating Better Auth into Next.js, Nuxt, or similar frameworks who require organization-level access control
• Security-focused architects who need to define and enforce granular permissions without building a custom authorization layer from scratch
• Product engineers adding team collaboration features to existing applications that already use Better Auth for authentication
• DevOps and platform engineers setting up internal tools where different departments need isolated access to resources
• Technical leads evaluating RBAC solutions who want a pattern that scales from small teams to enterprise-level organizations

Why Use It?

Problems It Solves

• Multi-tenant isolation is difficult to implement correctly without a dedicated abstraction layer, leading to data leakage between organizations when handled manually
• Custom role systems built from scratch are time-consuming and error-prone, especially when permission checks are scattered across multiple API routes
• Invitation workflows require careful state management, expiry handling, and email coordination, all of which the organization plugin handles out of the box
• Team segmentation within a single organization is often an afterthought, resulting in flat permission structures that cannot represent real organizational hierarchies
• Maintaining consistency between client-side UI gating and server-side permission enforcement is a common source of security vulnerabilities

Core Highlights

• Single plugin installation handles organization creation, membership, invitations, roles, and teams
• RBAC is enforced at the authentication layer, not the application layer
• Custom roles allow fine-grained permission definitions beyond the default owner, admin, and member roles
• Invitation system includes expiry, acceptance, and rejection workflows
• Team support enables sub-group management within a single organization
• CLI migration tool automates schema changes required by the plugin
• Client and server plugins stay synchronized, reducing configuration drift
• Compatible with any Better Auth-supported database adapter

How to Use It?

Basic Usage

Install and configure the plugin on both the server and client.

// server.ts
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [organization()],
});

// client.ts
import { createAuthClient } from "better-auth/client";
import { organizationClient } from "better-auth/plugins/client";

export const authClient = createAuthClient({
  plugins: [organizationClient()],
});

Run the database migration after adding the plugin:

npx @better-auth/cli migrate

Specific Scenarios

Scenario 1: Inviting a member to an organization

await authClient.organization.inviteMember({
  organizationId: "org_123",
  email: "newuser@example.com",
  role: "member",
});

Scenario 2: Defining a custom role with specific permissions

organization({
  roles: {
    billing: {
      permissions: ["read:invoices", "write:invoices"],
    },
  },
});

Real-World Examples

A project management SaaS uses organizations to isolate client workspaces, assigns admin roles to account owners, and uses teams to separate engineering and design groups within each client account.

An internal developer portal uses custom roles to grant read-only access to contractors while giving full write access to full-time engineers, all enforced at the auth layer.

When to Use It?

Use Cases

• Building a SaaS product where each customer account is an isolated organization
• Adding team collaboration to an existing single-tenant application
• Implementing department-level access control in an internal tool
• Managing contractor and vendor access with time-limited roles
• Structuring a marketplace where sellers and buyers have distinct permission sets
• Enforcing data isolation between business units in an enterprise application
• Replacing a custom-built role system with a standardized, maintainable alternative

Important Notes

Requirements

• Better Auth must be installed and configured before adding the organization plugin
• A supported database adapter must be connected, as the plugin requires schema migrations
• The CLI tool must be run after any plugin configuration changes to keep the schema current