Multi-Tenant Architecture

Hierarchical tenant isolation with Row-Level Security.

Tenant Hierarchy

Kanoniv supports a multi-tier tenant structure:

Platform Owner
    └── Organization (Tenant)
            └── Line of Business (Sub-tenant)
                    └── Environment (Sub-sub-tenant)

Use Cases

• SaaS Provider: Each customer is an Organization
• Large org: Each department is a Line of Business
• Multi-environment: Separate prod/staging/dev per tenant

Configuration

Tenants can have a parent relationship:

{
  "id": "tenant_sales",
  "name": "Sales Division",
  "parent_id": "tenant_acme",
  "settings": {
    "match_threshold": 0.85,
    "timezone": "America/New_York"
  }
}

Row-Level Security

Data isolation is enforced at the database level using PostgreSQL RLS.

Policy Implementation

CREATE POLICY tenant_isolation ON canonical_entities
    USING (tenant_id IN (SELECT get_tenant_hierarchy(current_tenant_id())));

Hierarchy Function

CREATE FUNCTION get_tenant_hierarchy(tenant_id UUID)
RETURNS TABLE(id UUID) AS $$
    WITH RECURSIVE hierarchy AS (
        SELECT id FROM tenants WHERE id = tenant_id
        UNION
        SELECT t.id FROM tenants t
        JOIN hierarchy h ON t.parent_id = h.id
    )
    SELECT id FROM hierarchy;
$$ LANGUAGE SQL SECURITY DEFINER;

What This Means

• Parent tenants can see their own data + all child tenant data
• Child tenants can ONLY see their own data
• No tenant can see sibling tenant data

Access Patterns

Parent Reads Child

An admin in tenant_acme can query all entities across:

• tenant_acme (self)
• tenant_sales (child)
• tenant_support (child)

Child Isolation

An admin in tenant_sales can ONLY query:

• tenant_sales (self)

API Tenant Context

The tenant context is set from the JWT claims:

{
  "tenant_id": "tenant_sales",
  "role": "admin"
}

All API queries are automatically scoped to this tenant and its children.

Cross-Tenant Queries (Platform Admin Only)

Platform administrators can query across all tenants:

Python

from kanoniv.client import KanonivClient

# Platform admin can query across all tenants
client = KanonivClient(api_key="kn_platform_admin_key")
# Cross-tenant queries use the admin API

curl

curl "https://api.kanoniv.com/v1/admin/entities?all_tenants=true" \
  -H "X-API-Key: kn_..."

This is audited and restricted to the platform_admin role.

Settings Inheritance

Child tenants can inherit settings from parents:

Setting	Inheritance
Match thresholds	Inheritable
Survivorship policy	Inheritable
Retention policies	Must be set per-tenant
SSO configuration	Per-tenant only

{
  "id": "tenant_sales",
  "settings": {
    "inherit_from_parent": ["match_threshold", "survivorship_policy"],
    "timezone": "Europe/London"
  }
}