Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Multi-Tenancy Patterns

:::info Coming Soon This feature is under active development. The design below reflects our planned implementation. :::

Organizations in Aero2 provide the building blocks for multi-tenant B2B applications. This page describes common architectural patterns.

Pattern 1: Organization per Customer

Each of your customers is represented as an organization. Users belong to their company's organization and can only access data scoped to that organization.

Best for: Traditional B2B SaaS where each customer is a separate company.

Example:
  • Acme Corp creates an organization and invites their employees.
  • Globex Inc creates a separate organization and invites their employees.
  • Acme users cannot see Globex data, and vice versa.

Pattern 2: Shared Users Across Organizations

Users can belong to multiple organizations simultaneously, similar to how Slack workspaces work. Users switch between organizations, and each organization has its own data and settings.

Best for: Platforms where users work across multiple teams or clients.

Example:
  • A freelance designer belongs to three client organizations.
  • They switch between organizations in the UI and see different projects and data for each.

Session Context

When a user belongs to multiple organizations, their session includes the concept of an active organization:

  • After sign-in, the user selects which organization they want to work in.
  • API calls are scoped to the active organization.
  • The user can switch organizations without re-authenticating.

Organization Claims in Tokens

When an active organization is set, JWT tokens will include organization-related claims:

{
  "sub": "user_abc123",
  "email": "jane@example.com",
  "org_id": "org_def456",
  "org_role": "admin",
  "org_permissions": ["org:manage", "org:members:write"]
}

Your backend can use these claims to enforce organization-level access control without additional API calls.