organization-best-practices

Overview

The organization skill from Better Auth enables backend developers to efficiently manage multi-tenant organizations, members, teams, and role-based access control (RBAC) within their applications. This skill is designed for projects that require advanced user management, such as SaaS platforms, internal tools, or any system where users belong to organizations with distinct roles and permissions.

With the organization skill, you can:

• Configure organizations with custom limits on creation and membership
• Manage invitations and onboard new members
• Define and assign custom roles and permissions
• Set up teams within organizations
• Implement RBAC for secure access control

This skill is a strong fit for teams building backend systems that need scalable, secure, and flexible organization management. It is less suitable for simple apps with no organizational structure or where single-user access is sufficient.

How to Use

Installation Steps

1. Add the organization plugin to your server configuration:

   import { betterAuth } from "better-auth";
   import { organization } from "better-auth/plugins";
   
   export const auth = betterAuth({
     plugins: [
       organization({
         allowUserToCreateOrganization: true,
         organizationLimit: 5, // Max organizations per user
         membershipLimit: 100, // Max members per organization
       }),
     ],
   });
   

2. Add the organization client plugin to your client configuration:

   import { createAuthClient } from "better-auth/client";
   import { organizationClient } from "better-auth/client/plugins";
   
   export const authClient = createAuthClient({
     plugins: [organizationClient()],
   });
   

3. Run database migrations:

   Run the following command to set up the necessary tables for organizations, members, and invitations:

   npx @better-auth/cli migrate
   

4. Verify your setup:

   Check your database to ensure the organization, member, and invitation tables have been created.

Creating and Managing Organizations

• Create an organization:

  The user who creates an organization 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" },
    });
  };
  

• Control who can create organizations:

  You can restrict organization creation based on user attributes by customizing the plugin options.

Customizing Roles and Permissions

Define custom roles and permissions to fit your application's needs. Use the plugin's configuration to set up RBAC and manage access at the organization or team level.

Best Practices

• Review the SKILL.md file for detailed configuration options and advanced usage.
• Adapt the provided code samples to fit your project's structure and requirements.
• Use the organization skill in projects where user grouping, team management, and granular access control are essential.

FAQ

Who should use the organization skill?

Backend developers building multi-tenant applications, SaaS products, or any system requiring robust organization and access control features will benefit most from this skill.

What are the prerequisites for installation?

You need a project using Better Auth and access to your backend and database for plugin configuration and migrations.

Can I customize organization limits and roles?

Yes, the organization skill allows you to set limits on the number of organizations per user, members per organization, and define custom roles and permissions.

Where can I find more details?

Check the SKILL.md file in the repository for advanced configuration, or explore the Files tab for supporting scripts and references.