Organizations

In this guide, we'll explore multi-tenant organization features with better-convex. You'll learn to set up the organization plugin, define roles and permissions, manage members and invitations, and implement team functionality.

Overview

Multi-tenant organization system with Better Auth's organization plugin:

Feature	Description
Organizations	Create, update, delete workspaces
Members	Role-based access within orgs
Invitations	Email invites with expiration
Teams	Group members within orgs
Access control	Custom permissions per role
Hooks	Lifecycle events for all operations

Let's set up organizations step by step.

Prerequisites

Ensure you have Auth Server set up before adding organizations.

1. Server Configuration

Add the organization plugin to your auth options:

convex/functions/auth.ts

import { organization } from 'better-auth/plugins';
import type { ActionCtx } from './_generated/server';

export const getAuthOptions = (ctx: GenericCtx) =>
  ({
    // ... existing config
    plugins: [
      convex({ authConfig, jwks: process.env.JWKS }),
      admin(),
      organization({
        ac,
        roles,
        allowUserToCreateOrganization: true,
        organizationLimit: 5,
        membershipLimit: 100,
        creatorRole: 'owner',
        invitationExpiresIn: 48 * 60 * 60, // 48 hours
        teams: {
          enabled: true,
          maximumTeams: 10,
        },
        sendInvitationEmail: async (data) => {
          await (ctx as ActionCtx).scheduler.runAfter(
            0,
            internal.email.sendOrganizationInviteEmail,
            {
              acceptUrl: `${process.env.SITE_URL!}/w/${data.organization.slug}?invite=${data.id}`,
              invitationId: data.id,
              inviterEmail: data.inviter.user.email,
              inviterName: data.inviter.user.name || 'Team Admin',
              organizationName: data.organization.name,
              role: data.role,
              to: data.email,
            }
          );
        },
      }),
    ],
  }) satisfies BetterAuthOptions;

2. Client Configuration

Add the organization client plugin:

src/lib/convex/auth-client.ts

import { organizationClient } from 'better-auth/client/plugins';
import { ac, roles } from '@convex/auth-shared';

export const authClient = createAuthClient({
  // ... existing config
  plugins: [
    inferAdditionalFields<Auth>(),
    convexClient(),
    organizationClient({
      ac,
      roles,
      teams: { enabled: true },
    }),
  ],
});

3. Schema

Add organization tables to your schema:

convex/functions/schema.ts

import {
  convexTable,
  defineSchema,
  id,
  index,
  integer,
  json,
  text,
  timestamp,
} from 'better-convex/orm';

export const organization = convexTable(
  'organization',
  {
    name: text().notNull(),
    slug: text().notNull(),
    logo: text(),
    createdAt: timestamp().notNull().defaultNow(),
    metadata: json<Record<string, unknown>>(),
  },
  (t) => [index('slug').on(t.slug), index('name').on(t.name)]
);

export const member = convexTable(
  'member',
  {
    organizationId: id('organization').notNull(),
    userId: id('user').notNull(),
    role: text().notNull(),
    createdAt: timestamp().notNull().defaultNow(),
  },
  (t) => [
    index('userId').on(t.userId),
    index('organizationId_userId').on(t.organizationId, t.userId),
    index('organizationId_role').on(t.organizationId, t.role),
  ]
);

export const invitation = convexTable(
  'invitation',
  {
    organizationId: id('organization').notNull(),
    inviterId: id('user').notNull(),
    email: text().notNull(),
    role: text(),
    status: text().notNull(),
    expiresAt: integer().notNull(),
    createdAt: timestamp().notNull().defaultNow(),
  },
  (t) => [
    index('email').on(t.email),
    index('status').on(t.status),
    index('email_organizationId_status').on(t.email, t.organizationId, t.status),
    index('organizationId_status').on(t.organizationId, t.status),
  ]
);

// Add these fields to your existing session table
export const session = convexTable('session', {
  // ... existing session fields
  activeOrganizationId: id('organization'),
  activeTeamId: id('team'),
});

export const tables = { organization, member, invitation, session };
export default defineSchema(tables, { strict: false });

Teams (Optional)

convex/functions/schema.ts

import { convexTable, id, index, integer, text, timestamp } from 'better-convex/orm';

export const team = convexTable(
  'team',
  {
    name: text().notNull(),
    organizationId: id('organization').notNull(),
    createdAt: timestamp().notNull().defaultNow(),
    updatedAt: integer(),
  },
  (t) => [index('organizationId').on(t.organizationId)]
);

export const teamMember = convexTable(
  'teamMember',
  {
    teamId: id('team').notNull(),
    userId: id('user').notNull(),
    createdAt: timestamp(),
  },
  (t) => [index('teamId').on(t.teamId), index('userId').on(t.userId)]
);

Additional Fields

Add custom fields to organization tables:

convex/functions/auth.ts

organization({
  schema: {
    organization: {
      fields: {
        description: v.optional(v.string()),
        website: v.optional(v.string()),
        industry: v.optional(v.string()),
        size: v.optional(v.string()),
      },
    },
    member: {
      fields: {
        title: v.optional(v.string()),
        department: v.optional(v.string()),
      },
    },
    invitation: {
      fields: {
        message: v.optional(v.string()),
      },
    },
  },
}),

Then update your schema to include these fields:

convex/functions/schema.ts

import { convexTable, text } from 'better-convex/orm';

export const organization = convexTable('organization', {
  // ... existing fields
  description: text(),
  website: text(),
  industry: text(),
  size: text(),
});

export const member = convexTable('member', {
  // ... existing fields
  title: text(),
  department: text(),
});

export const invitation = convexTable('invitation', {
  // ... existing fields
  message: text(),
});

4. Access Control

Define roles and permissions using Better Auth's access control system.

Basic Setup

convex/shared/auth-shared.ts

import { createAccessControl } from 'better-auth/plugins/access';
import {
  defaultStatements,
  memberAc,
  ownerAc,
} from 'better-auth/plugins/organization/access';

const statement = {
  ...defaultStatements,
  // Add custom resources as needed
} as const;

export const ac = createAccessControl(statement);

const member = ac.newRole({
  ...memberAc.statements,
});

const owner = ac.newRole({
  ...ownerAc.statements,
});

export const roles = { member, owner };

Custom Permissions

Define custom resources and permissions beyond the defaults:

convex/shared/auth-shared.ts

const statement = {
  ...defaultStatements,
  // Custom resources
  project: ['create', 'read', 'update', 'delete'],
  billing: ['read', 'update'],
  analytics: ['read'],
} as const;

export const ac = createAccessControl(statement);

// Custom roles with granular permissions
const viewer = ac.newRole({
  project: ['read'],
  analytics: ['read'],
});

const editor = ac.newRole({
  ...memberAc.statements,
  project: ['create', 'read', 'update'],
  analytics: ['read'],
});

const admin = ac.newRole({
  ...ownerAc.statements,
  project: ['create', 'read', 'update', 'delete'],
  billing: ['read', 'update'],
  analytics: ['read'],
});

export const roles = { viewer, editor, admin };

Check Role Permissions

// Check if a role has specific permission
const canEdit = ac.checkRolePermission({
  role: 'editor',
  permission: { project: ['update'] },
});

Dynamic Access Control

For runtime role creation (e.g., user-defined roles):

convex/functions/auth.ts

organization({
  ac: {
    ...ac,
    resolveRole: async ({ role, organizationId }) => {
      // Check if it's a built-in role
      if (roles[role]) return roles[role];

      // Fetch custom role from database
      const customRole = await ctx.orm.query.customRole.findFirst({
        where: { name: role, organizationId },
      });

      if (customRole) {
        return ac.newRole(customRole.permissions);
      }

      return null;
    },
  },
}),

Permission Helper

convex/lib/auth/auth-helpers.ts

import { CRPCError } from 'better-convex/server';
import type { AuthCtx } from '../crpc';

export const hasPermission = async (
  ctx: AuthCtx,
  body: { permissions: Record<string, string[]> },
  shouldThrow = true
) => {
  const result = await ctx.auth.api.hasPermission({
    body,
    headers: ctx.auth.headers,
  });

  if (shouldThrow && !result.success) {
    throw new CRPCError({
      code: 'FORBIDDEN',
      message: 'Insufficient permissions',
    });
  }

  return result.success;
};

Check Permission (Client)

// Check permission before showing UI
const { data } = await authClient.organization.hasPermission({
  permissions: { project: ['delete'] },
});

if (data?.success) {
  // Show delete button
}

Organization Functions

Pattern: Use Better Auth API for multi-table operations (create, delete, invitations). Use ctx.orm for simple reads/updates.

Function examples use the ORM via ctx.orm.