​

Multi-Tenancy Architecture

ProductFlo uses a sophisticated multi-tenant architecture that allows for secure data isolation between organizations while enabling cross-tenant collaboration when needed. This guide explains how the multi-tenancy system works and how to properly use it in your API integrations.

​

Schema-Based Isolation

ProductFlo implements schema-based tenant isolation at the database level. Each tenant (organization) gets its own PostgreSQL schema with dedicated tables.

​

Tenant Context

All API requests operate within a tenant context, which determines which data is accessible.

fetch('https://api.productflo.io/products', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Tenant-ID': 'tenant-123'
  }
})

​

Tenant Management

The following endpoints are available for managing tenants:

​

Tenant Context Pattern

The API automatically resolves the tenant context using the following priority:

1. X-Tenant-ID header (explicit tenant selection)
2. Default tenant from user settings
3. The first tenant the user has access to

​

Cross-Tenant Operations

Some operations can span multiple tenants when explicitly authorized. These operations use special endpoints with appropriate permission checks.

fetch('https://api.productflo.io/cross-tenant/product-sharing', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_tenant_id: 'tenant-123',
    target_tenant_id: 'tenant-456',
    product_id: 'product-789',
    permission_level: 'read'
  })
})

​

Tenant Data Model

Each tenant has the following structure:

{
  "id": "tenant-123",
  "name": "Acme Corporation",
  "schema_name": "tenant_123",
  "owner_id": "user-456",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-05-01T12:34:56Z",
  "settings": {
    "timezone": "America/New_York",
    "default_language": "en-US",
    "allowed_file_types": ["png", "jpg", "pdf", "step", "stl"],
    "branding": {
      "logo_url": "https://example.com/logo.png",
      "primary_color": "#1A73E8"
    }
  },
  "subscription": {
    "plan": "enterprise",
    "status": "active",
    "seats": 25,
    "features": ["advanced_ai", "cad_integration", "unlimited_storage"]
  }
}

​

Isolation Mechanisms

ProductFlo employs several mechanisms to ensure tenant isolation:

​

Database Isolation

• Each tenant gets a dedicated schema in PostgreSQL
• Schema names follow the pattern tenant_<id>
• Cross-schema queries require explicit privileges

​

API Isolation

• Tenant context is required for all data operations
• Middleware validates tenant access permissions
• API responses only include data from the active tenant

​

File Storage Isolation

• Files are organized in tenant-specific directories
• Access control lists (ACLs) protect files at the storage level
• File URLs contain tenant-specific signatures for verification

​

Best Practices

When working with the multi-tenant API, follow these best practices:

1. Always specify tenant context: Include the X-Tenant-ID header in all requests.

2. Validate tenant access: Check that users have appropriate permissions for the tenant they’re accessing.

3. Store tenant ID with data: When caching API responses, always associate them with the relevant tenant ID.

4. Handle tenant switching: Implement proper UI controls for users to switch between tenants they have access to.

5. Respect isolation boundaries: Don’t attempt to access data across tenants unless using explicit cross-tenant endpoints.

​

Security Considerations

The multi-tenant architecture includes several security features:

• Row-level security policies in the database
• Tenant validation middleware for all API requests
• Audit logging for cross-tenant operations
• Tenant-specific API rate limits
• Regular permission verification checks