跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

organization-best-practices

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.

krivoox · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add krivoox/agent-stack-template --skill organization-best-practices

技能说明


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

  1. Add organization() plugin to server config
  2. Add organizationClient() plugin to client config
  3. Run npx @better-auth/cli@latest migrate (built-in adapter) or generate + push for Drizzle/Prisma
  4. 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, // Max orgs per user
      membershipLimit: 100, // Max members per org
    }),
  ],
});

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) => {
    // Premium users get more organizations
    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", // `userId` is required
  },
});

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",
});

// Share data.url via any channel

This endpoint does not call sendInvitationEmail — handle delivery yourself.

Invitation Configuration

organization({
  invitationExpiresIn: 60 * 60 * 24 * 7, // 7 days (default: 48 hours)
  invitationLimit: 100, // Max pending invitations per org
  cancelPendingInvitationsOnReInvite: true, // Cancel old invites when re-inviting
});

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) {
  // User can manage members
}

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({ t

阅读完整来源 ↗