Multi Tenant Kit 🏢

Build powerful multi-tenant B2B SaaS applications with organization management, role-based access control, and subscription billing! ✨

What is Multi Tenant Kit? 🤔

The Multi Tenant Kit transforms Indie Kit into a complete B2B SaaS platform with:

• 🏢 Multi-Organization Support: Users can belong to multiple organizations
• 👥 Role-Based Access Control: Owner, Admin, and User roles with permissions
• 💳 Subscription Management: Integrate with Stripe or LemonSqueezy
• 👑 Super Admin Dashboard: Manage all organizations and plans
• 📊 Plan Quotas: Limit features based on subscription tiers
• ✉️ Team Invitations: Invite members to your organization
• 🔐 Secure API Routes: Built-in authentication wrappers

Installation 🚀

If you don't have the Multi Tenant Kit yet:

git clone https://github.com/Indie-Kit/b2b-boilerplate
cd b2b-boilerplate
pnpm install

Quick Navigation 🗺️

Jump to what you need:

• Database Structure - Understanding the data models
• Organizations - How organizations work
• Authentication - Securing your routes
• Roles & Permissions - Managing access control
• Invitations - Team management
• Plans & Billing - Subscription management
• Hooks & Utilities - Developer tools

Database Structure 🗄️

The Multi Tenant Kit uses a relational database structure designed for multi-tenancy:

Key Relationships 🔗

• Users ↔ Organizations: Many-to-many through OrganizationMembership
• Organizations → Plan: Each organization has one plan (or null for free tier)
• Organizations → Invites: Organizations can send multiple invitations
• Organizations → Billing: Connected to Stripe/LemonSqueezy for payments

Organizations 🏢

Organizations are the core of the Multi Tenant Kit! Users can create and join multiple organizations, each with its own team, subscription, and settings.

How Organizations Work 🔄

Think of organizations like workspaces in Slack or teams in Figma:

• 👤 Multiple Users: An organization can have many team members
• 👥 Multiple Organizations Per User: Users can belong to many organizations
• 🎭 Different Roles: Each user has a specific role in each organization
• 💳 Independent Billing: Each organization has its own subscription
• ⚙️ Isolated Data: Organization data is completely separated

Organization Features ✨

1. Unique Identity

• ID, name, and slug for URL routing
• Optional organization image/logo
• Timestamps for tracking

2. Role-Based Access Control

• Owner: Full control (billing, deletion, everything)
• Admin: Manage members and settings
• User: Basic access to features

3. Onboarding System

• Track if onboarding is complete
• Store onboarding data (JSON)
• Custom onboarding flows

4. Billing Integration

• Stripe or LemonSqueezy support
• Customer and subscription IDs stored
• Automatic plan assignment

5. Plan Management

• Each organization has a plan (or null for free)
• Plan quotas control feature access
• Easy plan upgrades/downgrades

Authentication & Security 🔐

The Multi Tenant Kit includes powerful authentication wrappers to protect your API routes. Choose the right wrapper for your security needs!

Three Levels of Protection 🛡️

1. Basic Authentication: withAuthRequired 👤

Requires user to be logged in. Perfect for personal features:

// src/app/api/app/profile/route.ts
import withAuthRequired from "@/lib/auth/withAuthRequired";

export const GET = withAuthRequired(async (req, context) => {
  const user = await context.session.user;
  
  // Fetch user's personal data
  const profile = await getUserProfile(user.id);
  
  return NextResponse.json(profile);
});

Use this for:

• User profile endpoints
• Personal settings
• User-specific data (not org-specific)

2. Organization Authentication: withOrganizationAuthRequired 🏢

Requires user to belong to the organization + optional role check:

// src/app/api/app/org/[slug]/settings/route.ts
import withOrganizationAuthRequired from "@/lib/auth/withOrganizationAuthRequired";
import { OrganizationRole } from "@/db/schema/organization";

export const PATCH = withOrganizationAuthRequired(
  async (req, context) => {
    const organization = await context.session.organization;
    const body = await req.json();
    
    // Update organization settings
    await updateSettings(organization.id, body);
  
  return NextResponse.json({ success: true });
  },
  OrganizationRole.enum.admin // Only admin or owner
);

Use this for:

• Organization resources (projects, documents, etc.)
• Team settings
• Member management
• Anything scoped to an organization

Learn more about Organization Auth →

3. Super Admin Authentication: withSuperAdminAuthRequired 👑

Requires super admin privileges. For platform management only:

// src/app/api/super-admin/organizations/route.ts
import withSuperAdminAuthRequired from "@/lib/auth/withSuperAdminAuthRequired";

export const GET = withSuperAdminAuthRequired(async (req, context) => {
  // Fetch all organizations (admin view)
  const allOrgs = await getAllOrganizations();
  
  return NextResponse.json(allOrgs);
});

Use this for:

• Managing all organizations
• Creating/editing plans
• Platform analytics
• User impersonation

Roles & Permissions 👥

The Multi Tenant Kit uses a simple but powerful three-tier role system:

export const roleEnum = pgEnum("role", ["owner", "admin", "user"]);

Role Hierarchy 📊

👑 Owner (Level 2)
  ↓ Can do everything
👤 Admin (Level 1)
  ↓ Can do most things
🙂 User (Level 0)
  ↓ Can use features

Role Permissions 🔑

Role Checking in Code 💻

The hasHigherOrEqualRole function compares roles:

const roleHierarchy = {
  user: 0,
  admin: 1,
  owner: 2,
};

// Check if user can perform admin actions
if (hasHigherOrEqualRole({ 
  currentRole: userRole, 
  requiredRole: 'admin' 
})) {
  // Allow action
}

This means:

• Owners can do everything Admins and Users can do
• Admins can do everything Users can do
• Users have only their own permissions

Learn more about managing roles →

Invitations & Memberships ✉️

Build your team by inviting members to your organization!

How Memberships Work 👥

Organization memberships connect users to organizations:

OrganizationMembership {
  organizationId: string  // Which organization
  userId: string          // Which user
  role: 'owner' | 'admin' | 'user'  // Their role
  createdAt: timestamp
  updatedAt: timestamp
}

Key Features:

• One user can belong to multiple organizations
• Each membership has a specific role
• Composite primary key prevents duplicates
• Timestamps track when they joined

The Invitation System 📨

Admins and Owners can invite new members:

OrganizationInvite {
  id: string              // Unique invite ID
  email: string           // Invitee's email
  organizationId: string  // Target organization
  role: 'owner' | 'admin' | 'user'  // Assigned role
  token: string           // Verification token
  expiresAt: timestamp    // When invite expires
  createdAt: timestamp
}

How it Works:

1. Admin/Owner sends invite with email and role
2. System creates invite with unique token
3. Email sent to invitee with link
4. Invitee clicks link, creates account (if needed)
5. Membership created automatically
6. Invite marked as used or deleted

Learn more about inviting members →

Plans & Subscriptions 💳

Monetize your B2B SaaS with flexible subscription plans!

Understanding Plans 📊

Plans define what organizations can do and how much they pay:

Plan Structure:

• Name and codename (for URLs)
• Default flag (free tier)
• Pricing tiers (monthly, yearly, one-time)
• Payment provider integration
• Feature quotas

Supported Pricing Models:

• 💰 Monthly: Recurring monthly charge
• 📅 Yearly: Annual subscription (usually discounted)
• 🎯 One-time: Lifetime access or credits

Payment Providers:

• Stripe (recommended)
• LemonSqueezy

Creating Plans (Super Admin) 👑

Plans are managed through the super admin dashboard:

1. Navigate to /super-admin/plans
2. Click "Create Plan"
3. Fill in the details:

Plan Details:
├─ Name: "Professional"
├─ Codename: "pro"
├─ Default: false
├─ Monthly Price: $49
├─ Yearly Price: $490 (save $98!)
├─ Stripe Price IDs
└─ Quotas: { projects: 100, users: 50 }

4. Save and it's live!

Generating Subscription Links 🔗

Use getSubscribeUrl to create subscription links:

import Link from "next/link";
import getSubscribeUrl from "@/lib/plans/getSubscribeUrl";
import { PlanType, PlanProvider } from "@/lib/plans/getSubscribeUrl";

export function PricingCard() {
  return (
    <div className="pricing-card">
      <h3>Pro Plan</h3>
      <p>$49/month</p>
      
      <Link
        href={getSubscribeUrl({
  codename: "pro",
  type: PlanType.MONTHLY,
  provider: PlanProvider.STRIPE,
          trialPeriodDays: 7  // Optional 7-day trial
        })}
        className="btn-primary"
      >
        Start Free Trial
</Link>
    </div>
  );
}

getSubscribeUrl Parameters:

• codename: Plan identifier (e.g., "pro", "enterprise")
• type: MONTHLY, YEARLY, or ONETIME
• provider: STRIPE or LEMON_SQUEEZY
• trialPeriodDays: Optional trial period

Checking Plan Quotas in Code 📏

Enforce plan limits in your application:

'use client'

import { useOrganization } from '@/lib/organizations/useOrganization'

export function CreateProjectButton() {
  const { organization } = useOrganization()
  
  // Check if they can create more projects
  const currentProjects = 45  // From your database
  const maxProjects = organization.plan?.quotas.projects || 10
  const canCreate = currentProjects < maxProjects
  
  return (
    <button disabled={!canCreate}>
      {canCreate ? 'Create Project' : `Upgrade to create more (${currentProjects}/${maxProjects})`}
    </button>
  )
}

Hooks & Utilities 🪝

The Multi Tenant Kit provides powerful React hooks and utility functions for your application!

useOrganization Hook 🏢

Your go-to hook for accessing organization data in client components:

'use client'

import { useOrganization } from '@/lib/organizations/useOrganization'

export default function Dashboard() {
  const {
    organization,      // Current org data with plan and role
    isLoading,         // Loading state
    error,             // Error state  
    mutate,            // Refresh data
    switchOrganization // Switch to another org
  } = useOrganization()
  
  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error loading organization</div>
  
  return (
    <div>
      <h1>{organization.name}</h1>
      <p>Plan: {organization.plan?.name}</p>
      <p>Your Role: {organization.role}</p>
    </div>
  )
}

What you get:

• Organization name, slug, image
• Current user's role in the organization
• Plan details and quotas
• Loading and error states
• Functions to refresh or switch organizations

Full useOrganization documentation →

Organization Utility Functions 🛠️

Server-side utilities for working with organizations:

getUserOrganizations(userId)

Fetches all organizations a user belongs to:

const userOrgs = await getUserOrganizations(userId);
// Returns: Array<{id, name, slug, image, role, onboardingDone}>

getUserOrganizationById(userId, organizationId)

Fetches a specific organization with plan:

const org = await getUserOrganizationById(userId, organizationId);
// Returns: {id, name, slug, role, plan: {id, name, quotas, ...}}

createOrganization(name, creatorId)

Creates a new organization:

const newOrg = await createOrganization("Acme Corp", userId);
// Creator automatically becomes owner

hasHigherOrEqualRole({currentRole, requiredRole})

Checks if a role meets requirements:

if (hasHigherOrEqualRole({
  currentRole: 'admin',
  requiredRole: 'admin'
})) {
  // Allow action
}

userBelongsToOrganization(userId, organizationId)

Verifies membership:

const isMember = await userBelongsToOrganization(userId, orgId);
// Returns: boolean

Quick Start Guide 🚀

Ready to build? Here's how to get started:

1. Install Multi Tenant Kit ✅

git clone https://github.com/Indie-Kit/b2b-boilerplate
cd b2b-boilerplate
pnpm install

2. Set Up Database 🗄️

pnpm db:push  # Push schema to database

3. Create Your First Plan 💳

1. Run the app: pnpm dev
2. Make yourself super admin (check docs)
3. Go to /super-admin/plans
4. Create a "Free" plan with default: true
5. Create paid plans (Pro, Enterprise, etc.)

4. Build Organization Features 🏢

Use the provided hooks and wrappers:

// Client component with organization data
'use client'
import { useOrganization } from '@/lib/organizations/useOrganization'

// API route with organization auth
import { withOrganizationAuthRequired } from '@/lib/auth/withOrganizationAuthRequired'

5. Test Everything ✨

• Create an organization
• Invite team members
• Subscribe to a plan
• Test role permissions
• Verify quota enforcement

Related Documentation 📚

Deep dive into specific topics:

• Organization Roles - Managing permissions
• useOrganization Hook - Client-side hook
• withOrganizationAuthRequired - API security
• Inviting Team Members - Team management

Need Help? 💬

• Check the Indie Kit Docs
• Join the Discord Community
• Contact support for license holders