​
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.
This approach provides strong data isolation guarantees while still allowing for efficient resource sharing and cross-tenant operations when needed.

​
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:

POST /tenant/create

Create a new tenant (organization)

GET /tenants

List all tenants the authenticated user has access to

GET /tenant/{tenant_id}

Get details about a specific tenant

PUT /tenant/{tenant_id}

Update tenant settings

​
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
Always explicitly set the tenant context when making API requests to avoid unintended cross-tenant data access.

​
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