Organizations

Turbocamp includes a comprehensive multi-tenant organization system built with Better Auth's organization plugin. This allows your users to create teams, invite members, and manage permissions.

Overview

The organization system provides:

• Multi-tenant Architecture - Users can belong to multiple organizations
• Role-Based Access Control - Owner, admin, and member roles
• Team Management - Invite, remove, and manage team members
• Organization Switching - Seamless context switching
• Scoped Resources - Data isolation between organizations

Key Features

Organization Creation

Users can create organizations with:

• Custom organization name
• URL-friendly slug
• Logo upload (coming soon)
• Metadata storage for custom fields

Member Management

Organization owners and admins can:

• Invite new members via email
• Assign roles (admin or member)
• Remove members
• Update member permissions

Role Hierarchy

Implementation Guide

Creating an Organization

const result = await organization.create({
  name: "Acme Inc",
  slug: "acme-inc", // Optional, auto-generated if not provided
});

await organization.setActive({
  organizationId: result.data.id,
});

Managing Members

Inviting Members

await organization.inviteMember({
  organizationId: activeOrg.id,
  email: "colleague@example.com",
  role: "member", // or "admin"
});

Updating Member Roles

await organization.updateMemberRole({
  organizationId: activeOrg.id,
  memberIdOrEmail: memberId,
  role: "admin",
});

Removing Members

await organization.removeMember({
  organizationId: activeOrg.id,
  memberIdOrEmail: memberId,
});

Organization Switching

The organization switcher is available in the dashboard sidebar:

// Get list of user's organizations
const { data: organizations } = useListOrganizations();

// Get current active organization
const { data: activeOrg } = useActiveOrganization();

// Switch to a different organization
await organization.setActive({
  organizationId: orgId,
});

Database Schema

The organization system uses these Prisma models:

model Organization {
  id          String       @id
  name        String
  slug        String?
  logo        String?
  createdAt   DateTime
  metadata    String?
  members     Member[]
  invitations Invitation[]
  
  @@unique([slug])
}

model Member {
  id             String       @id
  organizationId String
  organization   Organization @relation(...)
  userId         String
  user           User         @relation(...)
  role           String
  createdAt      DateTime
}

model Invitation {
  id             String       @id
  organizationId String
  organization   Organization @relation(...)
  email          String
  role           String?
  status         String
  expiresAt      DateTime
  inviterId      String
  user           User         @relation(...)
}

API Endpoints

Better Auth automatically provides these endpoints:

• POST /api/auth/organization.create - Create new organization
• POST /api/auth/organization.update - Update organization details
• POST /api/auth/organization.delete - Delete organization
• POST /api/auth/organization.setActive - Switch active organization
• POST /api/auth/organization.inviteMember - Send invitation
• POST /api/auth/organization.removeMember - Remove member
• POST /api/auth/organization.updateMemberRole - Change member role
• GET /api/auth/organization.getFullOrganization - Get organization with members

Configuration

Organizations are configured in packages/auth/server.ts:

import { organization } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    organization({
      allowUserToCreateOrganization: true,
      organizationLimit: 5,
      membershipLimit: 100,
      creatorRole: 'owner',
      sendInvitationEmail: async (data) => {
        // Implement email sending
        await sendEmail({
          to: data.email,
          subject: `Invitation to join ${data.organization.name}`,
          // ... email template
        });
      },
    }),
  ],
});

Best Practices

1. Scope All Resources - Always filter data by organization ID
2. Check Permissions - Verify user roles before allowing actions
3. Handle Edge Cases - Users with no organizations, deleted organizations
4. Audit Logging - Track organization changes for compliance
5. Rate Limiting - Prevent abuse of invitation system

Troubleshooting

Common Issues

if (!activeOrg && organizations.length === 0) {
  router.push('/organization/new');
}

const member = organization.members.find(m => m.userId === user.id);
if (member.role !== 'owner' && member.role !== 'admin') {
  throw new Error('Insufficient permissions');
}

sendInvitationEmail: async (data) => {
  // Ensure email service is configured
  if (!process.env.RESEND_API_KEY) {
    console.log('Email invitation:', data);
    return;
  }
  // Send actual email
}

Next Steps

• Set up email service for invitations
• Configure billing per organization
• Implement webhooks for organization events
• Add custom roles beyond owner/admin/member