Skip to content
TruthVouch Docs

Multi-Tenant Architecture

TruthVouch is a multi-tenant SaaS platform where many organizations share infrastructure while maintaining complete data isolation. This guide explains isolation mechanisms.

Isolation Layers

Layer 1: Authentication & JWT-Based Tenant Identification

Every API request includes a JWT token that identifies the authenticated tenant (organization). The JWT payload contains the tenant ID (clientId), which is cryptographically verified before any database access. This ensures only authenticated, identified tenants can make requests.

Layer 2: Application-Layer Data Filtering

Every database query is automatically filtered by the authenticated tenant’s ID. There is no way for one tenant to access another tenant’s data through the API. The tenant context is extracted from the JWT claims and applied at the data access layer, ensuring all queries return only data belonging to the authenticated tenant.

This filtering is enforced consistently across all data access patterns — whether direct queries, service methods, or API endpoints.

Data Isolation Verification

Verify your data is isolated:

# Query your data
my_data = client.truth_nuggets.list()


# Verify no one else can access it
# Try different authentication token
other_client = TruthVouch(api_key="different-api-key")
try:
    other_data = other_client.truth_nuggets.list()
    # Should be empty or different tenant's data
except Unauthorized:
    # Correct: access denied

Audit Trail Isolation

Audit logs are global but client-filtered:

Global audit_logs table:
id | client_id | event | timestamp | ...


Query: SELECT * FROM audit_logs
Result: Only rows where client_id = current_client

You see your audit trail, nothing else.

Cache Isolation

All caching layers are namespaced by tenant, ensuring complete isolation. Each client’s cached data is only accessible within their own tenant context — there is no cross-tenant cache contamination.

Backup Isolation

Backups are encrypted and tagged by client:

backup_2024_01_15_org_abc123.sql.enc
backup_2024_01_15_org_xyz789.sql.enc


Restoration: Restore entire database with tenant isolation verified

Tenant Context Propagation

Tenant context flows through the entire request lifecycle:

API Request (with JWT)
  ↓
Authentication: Verify JWT signature
  ↓
Extract tenant ID from JWT claims
  ↓
Authorization: Apply tenant filter to all data access
  ↓
Database: Query returns only authenticated tenant's data
  ↓
Response: Encrypted and returned to client

Penetration Testing

Third-party pentesters verify isolation:

  • Attempt cross-tenant data access
  • Try JWT tampering
  • Test SQL injection
  • Verify tenant isolation enforcement
  • Check cache isolation

Goal: Verify zero cross-tenant data access through regular penetration testing.

Compliance

  • GDPR: Data strictly isolated per controller
  • SOC 2: Multi-tenancy isolation designed for SOC 2 compliance
  • HIPAA: Application-layer tenant isolation enforces HIPAA-required access controls
  • ISO 42001: Isolation designed per AI governance standards

Next Steps

  • Data Handling: Encryption and key management
  • Security Overview: Full security posture
  • GDPR: Data subject rights and DPA