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:

python
email = models.EmailField(db_index=True) // unique=True removed

class Meta:
    constraints = [
        // 1. Runtime Plane Isolation (End-users)
        // The same email can exist millions of times, as long as each 
        // belongs to a different project.
        models.UniqueConstraint(
            fields=["email", "project"],
            name="uniq_user_email_per_project",
        ),
        // 2. Control Plane Isolation (Developers)
        // Developers managing HVT must remain globally unique.
        models.UniqueConstraint(
            fields=["email"],
            condition=Q(project__isnull=True),
            name="uniq_user_email_when_project_null",
        ),
    ]

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.
Mathematical Isolation
By ensuring every authentication lookup requires the API key instance, it becomes mathematically impossible for an API request to interact with or authenticate a user from a different tenant.

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.