Organizations & Tenancy

Welcome to the Organizations & Tenancy guide! If you're building a SaaS application, multi-tenancy is crucial for scaling and isolating customer data. This guide will walk you through how the SaaS Boilerplate implements organizations as the core tenant model, ensuring secure data isolation while allowing users to belong to multiple organizations. We'll cover the data model, roles, API scoping, and practical examples to help you understand and extend this system.

Why Multi-Tenancy Matters

In a SaaS application, multi-tenancy means serving multiple customers (tenants) from a single codebase and database, while keeping their data completely separate. Organizations in the SaaS Boilerplate represent these tenants—each company or team gets its own isolated workspace.

Key benefits:

• Scalability: One app serves many customers without code duplication.
• Security: Data is strictly isolated; users can't access data from other organizations.
• Flexibility: Users can belong to multiple organizations (e.g., personal and work accounts).

Without proper tenancy, you'd risk data leaks or complex workarounds. The boilerplate uses organization-scoped queries and session-based access control to enforce isolation.

How Organizations Work

User Membership and Active Organization

A user can join multiple organizations through memberships. Each membership has a role (owner, admin, member) that determines permissions.

The "active organization" is stored in the user's session. This shapes what data they see and what actions they can perform. For example:

• When viewing leads, only those from the active organization appear.
• API calls automatically filter by the active organization's ID.

If a user isn't in any organization, they're prompted to create or join one during onboarding.

Data Isolation

All business data (leads, submissions, webhooks, etc.) belongs to an organization. Database queries always include organizationId filters. This ensures:

• Users only see their organization's data.
• Admins can't accidentally access other tenants' info.
• API keys and integrations are organization-specific.

Data Model Overview

The organization system revolves around these core entities. Let's break down the key models from prisma/schema.prisma:

Organization Model Details

The Organization model is the heart of tenancy:

Member Model Details

Members connect users to organizations:

Invitation Model Details

For inviting new members:

Roles and Permissions

Roles control what users can do within an organization. The boilerplate uses a simple hierarchy:

Implementing Role Checks

Permissions are enforced in procedures (server-side functions). For example:

// In a procedure
const session = await context.auth.getSession({
  requirements: 'authenticated',
  roles: ['admin', 'owner'], // Require specific roles
});

// Only admins/owners can proceed

Guidelines for roles:

• Least privilege: Default to "member" for new users.
• Explicit checks: Always verify roles for sensitive operations.
• Avoid sprawl: Keep roles simple; use metadata for fine-grained permissions if needed.

API Scoping and Controllers

All API endpoints respect organization boundaries. Controllers read the active organization from the session and filter queries accordingly.

Example: Creating an Organization

export const OrganizationController = igniter.controller({
  name: 'Organization',
  path: '/organization',
  actions: {
    create: igniter.mutation({
      // ... config
      handler: async ({ request, response, context }) => {
        const session = await context.auth.getSession({ requirements: 'authenticated' });
        // Create org and set as active
        const org = await context.organization.create({
          name: request.body.name,
          slug: request.body.slug,
          userId: session.user.id,
        });
        return response.created(org);
      },
    }),
    // ... other actions
  },
});

// Get leads for active org
const leads = await context.lead.list({
  organizationId: session.organization.id,
});

if (!session.organization) {
  return response.forbidden('No active organization');
}

Key Endpoints

From the OpenAPI spec:

• POST /organization: Create new org.
• GET /organization/stats: Get org analytics.
• PUT /organization: Update org details.
• POST /invitation: Invite members.
• GET /membership: List org members.

All require authentication and active organization.

Practical Examples

Onboarding a New User

1. User signs up → No organization yet.
2. Prompt to create org: POST /organization with name/slug.
3. Auto-set as active org in session.
4. User can now add members, resources.

Switching Organizations

1. User has multiple memberships.
2. Call POST /auth/set-active-organization with org ID.
3. Session updates; UI refreshes with new org's data.

Inviting Members

1. Admin calls POST /invitation with email/role.
2. Invitee receives email with accept link.
3. On accept: POST /invitation/:id/accept → Creates membership.

Troubleshooting

Best Practices