Tenant Isolation Architecture
How HVT handles user multi-tenancy and data isolation across different planes, allowing the same email to exist safely across isolated projects.
1. The Global Email Constraint Problem
Before this architectural refactor, HVT enforced email uniqueness globally across the entire platform. As a multi-tenant Identity Provider, HVT operates across two distinct planes:
- Control Plane: Developers who log into the HVT dashboard to manage their organizations.
- Runtime Plane: End-users (customers) who sign up for the apps built by developers.
Because of the global email constraint, user pools were bleeding into each other. If [email protected] signed up for Developer A's fitness app, HVT prevented that same email from signing up for Developer B's e-commerce app.
2. The Two-Plane Isolation Solution
To achieve Auth0-level isolation, the system was refactored to treat the database as partitioned silos based on the project_id injected via the X-API-Key.
Database Model Changes
Global uniqueness of the email field was removed and replaced with strict, scope-aware constraints at the database level:
Identity Resolution Layer
Because the database now contains duplicate emails, querying merely by email would cause errors. All user queries are routed through a dedicated identity layer that enforces API Key context:
get_control_plane_users_by_email: Retrieves dashboard developers by ensuring the project is null.get_runtime_user_for_api_key(email, api_key): Resolves the exact Runtime user by ensuring they belong to the organization and project connected to the active API key.
Serializer and Flow Separation
Legacy standard serializers that performed global email lookups were completely replaced with plane-specific logic:
- Registration: Limits existence validation strictly to the boundaries of the associated API key project.
- Password Reset: Split into Control Plane workflows (null project) and Runtime Plane workflows (validating against the specific project attached to the active API Key).
- Login & Signals: Auth hooks inspect the request. If an API key is present, it looks for the user in the Runtime Plane; otherwise, it defaults to the Control Plane.
3. Backward Compatibility
To ensure existing integrations continued working flawlessly during this change:
- Migration Handlers: Custom RunPython migrations safely dropped the strict unique email indexes generated by earlier libraries without wiping any data.
- Legacy User Fallbacks: If a user was created in an older system version where they lacked a project assignment but had an organization, a new matching function gracefully allows them into their legacy structure while strictly enforcing the new rules for newly created accounts.