Skip to main content

Identity & Tenancy - Version Mapping

Shows which product versions use this domain and to what extent.

Version Matrix​

VersionScopeTables UsedKey Features
MVP.0Fullorganizations, accounts, users, membershipsCore multi-tenancy, Google SSO, org/account isolation, admin role assignment
MVP.1Full(no changes)Row-Level Security policies enforced, multi-org user switching enabled
V1.0Full+parent_account_id (column)Account hierarchy, management company sub-accounts, permission inheritance
V1.1Full(no changes)Multi-org switching UI, session scoped to active org/account, recent org list
V1.2Full+auth integration tablesSAML SSO, SCIM provisioning, group-based role assignment
V2.0Full+identity_providers, user_identitiesFederated identity, cross-org federation, delegated authentication

Changes by Version​

MVP.0 - Foundation​

Scope: Full implementation of core identity and tenancy model.

Tables:

  • organizations - Top-level tenant boundary
  • accounts - Sub-tenant actors within orgs
  • users - Global individual identity
  • memberships - Binding of users to org/account with roles

Features:

  • Multi-tenancy isolation via org_id filtering (application layer)
  • Google SSO integration (OAuth 2.0 + OIDC + PKCE)
  • Auto-create default Account on Org creation
  • Admin role assignment to org creator
  • Email-based global user identity (case-insensitive)
  • Account-level and org-wide membership scoping
  • Soft deletes for audit compliance
  • Membership audit trail (invited_by, invited_at, ended_at)

Business Rules:

  • Every Org must have exactly one default Account (is_default=true)
  • User email must be globally unique
  • Memberships with account_id=NULL grant org-wide access
  • All actor-owned entities must reference account_id

Implementation Details:

  • 4 tables total
  • 12+ indexes for query performance
  • 8+ constraints for data integrity
  • RLS policies defined but not enforced (activated in MVP.1)

MVP.1 - Security Hardening​

Scope: Full - Enhanced security enforcement.

Changes from MVP.0:

  • Row-Level Security (RLS) policies enforced at database level
  • Multi-org user switching enabled (UI support)
  • Session tracking improvements
  • Enhanced org isolation guarantees

New Features:

  • Automatic org_id filtering via RLS (removes application layer requirement)
  • Users can belong to multiple Orgs
  • Active org/account context in user session
  • Improved invitation flow with pending status tracking

Technical Changes:

  • Enable RLS on all tables: organizations, accounts, users, memberships
  • Add policies: org members can read org data, account members can read account data
  • Application-layer org_id filters supplemented by database enforcement
  • Performance optimization for RLS policy evaluation

V1.0 - Account Hierarchy​

Scope: Full - Extended account model with parent-child relationships.

Changes from MVP.1:

  • Add parent_account_id column to accounts table
  • Support management companies with sub-accounts
  • Permissions inheritance from parent to child accounts

New Tables:

  • None (schema extension only)

Enhanced Features:

  • Hierarchical account structure (parent → children)
  • Management company accounts can have property owner sub-accounts
  • Inherited permissions flow down hierarchy
  • Recursive queries for account tree traversal

Business Rules:

  • Parent accounts can view all child account data
  • Child accounts isolated from siblings
  • Circular references prevented via constraint
  • Maximum hierarchy depth: 3 levels

Use Cases:

  • Property management companies managing multiple owner accounts
  • Brand organizations with franchise locations
  • Multi-property owner portfolios

V1.1 - User Experience Enhancement​

Scope: Full - Improved multi-org workflows.

Changes from V1.0:

  • UI for switching between Orgs (no schema changes)
  • Session context tracks active Org + Account
  • Recent Org list for quick switching
  • User preferences per Org

New Features:

  • Org switcher in navigation header
  • Last-used org remembered per user
  • Org-specific notification preferences
  • Breadcrumb navigation showing active org/account

Implementation:

  • Add last_active_org_id to users table (nullable)
  • Session JWT includes active_org_id claim
  • Frontend state management for org context
  • API middleware validates requests against active org

V1.2 - Enterprise Identity​

Scope: Full - Directory integration for enterprise customers.

Changes from V1.1:

  • SAML SSO support (alternative to Google SSO)
  • SCIM for automated user provisioning
  • Group-based role assignment

New Tables:

  • saml_configurations - Per-org SAML IdP settings
  • scim_tokens - API tokens for SCIM endpoints
  • directory_groups - Synced from IdP (AD, Okta, etc.)
  • group_memberships - Links users to directory groups
  • role_group_mappings - Automatic role assignment by group

Enhanced Features:

  • Enterprise SSO with custom IdP
  • Automatic user provisioning/deprovisioning
  • Group-based access control
  • Just-in-time (JIT) user creation
  • Multiple authentication providers per org

Business Rules:

  • SAML configuration scoped to Org (one IdP per Org)
  • SCIM tokens follow OAuth 2.0 bearer token pattern
  • Group memberships synchronized hourly
  • Role assignments updated on group membership change

Compliance:

  • SOC 2 Type II requirements for enterprise customers
  • Audit trail for all provisioning events
  • Support for IdP-initiated SSO flows

V2.0 - Federated Identity​

Scope: Full - Cross-platform identity federation.

Changes from V1.2:

  • Support for external identity providers (beyond Google/SAML)
  • Cross-org identity federation
  • Delegated authentication workflows

New Tables:

  • identity_providers - Configurable auth providers (Google, Microsoft, GitHub, custom OIDC)
  • user_identities - Provider-specific user profiles (one user → many identities)
  • federation_links - Cross-org identity mappings
  • authentication_logs - Complete audit trail per authentication attempt

Enhanced Features:

  • Multi-provider authentication (user chooses at login)
  • Account linking across providers (merge identities)
  • Federated sessions spanning multiple orgs
  • Trust relationships between orgs
  • Delegated access without account duplication

Business Rules:

  • Primary identity required (user.email remains unique)
  • Secondary identities linked via user_identities table
  • Federation requires mutual consent from both orgs
  • Federated sessions expire faster (6 hours vs. 24 hours)

Use Cases:

  • Users accessing partner org resources without separate login
  • Channel managers accessing multiple property owner orgs
  • Marketplace platforms federating with supplier accounts

Security:

  • Provider-specific token encryption at rest
  • Refresh token rotation per provider
  • Anomaly detection across federated sessions
  • IP-based geofencing per org

Operational Notes​

MVP.0 Performance Targets​

  • User login: <500ms (including SSO callback)
  • Org creation: <300ms (includes default account creation)
  • Membership query: <50ms (cached)

Monitoring Requirements​

  • Track org creation rate (growth metric)
  • Monitor RLS policy hit rate (post-MVP.1)
  • Alert on membership changes (security)
  • Track SSO failure rate

Scaling Considerations​

  • Organizations table grows linearly with customer acquisition
  • Users table growth rate depends on team size per org
  • Memberships table is hottest (most queries join through this)
  • Indexes critical for org_id, user_id, account_id lookups

Backup & Retention​

  • Soft deletes only (never hard delete)
  • Ended memberships retained indefinitely
  • Org data retained 7 years post-deletion (compliance)
  • User data subject to GDPR erasure with audit record