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

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

Pattern 1: Organization per Customer

Each customer is represented as a single organization. Users belong to their company's organization and only see data scoped to it.

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, like Slack workspaces. Each organization keeps 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 your application's UI and see different projects for each.

Available Today

  • Organizations API — create, list (per user), update, delete, soft-isolated per Application.
  • Members API — list/update/remove with a last-admin guard.
  • Invitations API — send, list, revoke, accept; tokens are 64 hex characters, single-use, with a configurable TTL.
  • Active-organization session claim + switcher — see "Session Context" below.
  • Audit events — org_created, org_updated, org_deleted, member_role_changed, member_removed, org_invitation_sent, org_invitation_revoked, org_invitation_accepted, org_activated.

Session Context

When a user belongs to multiple organizations, their session can pin a single active organization:

  • After sign-in, the user picks an organization in the dashboard's org switcher (rendered automatically when the user belongs to ≥ 2 orgs in the current application).
  • The switcher calls POST /api/organizations/:id/activate, which verifies membership, revokes the previous session row, and mints a new session JWT with an active_org_id claim — without re-authenticating the user.
  • Your backend can read the claim from the verified session JWT to scope queries.

Organization Claims in Tokens

After a successful activate call, the session JWT carries:

{
  "sub": "user_abc123",
  "email": "jane@example.com",
  "auth_time": 1715608800,
  "active_org_id": "org_def456"
}

The claim is a hint — the source of truth for membership remains organization_members, so a stale or forged active_org_id never grants access on its own. auth_time is preserved across activate so a context switch can't reset the step-up freshness clock that guards account-destructive routes.

Per-organization roles and permissions (org:manage, org:members:write, …) are tracked as a Phase 5 follow-up.