> ## Documentation Index
> Fetch the complete documentation index at: https://docs.productflo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Tenancy

> How ProductFlo implements multi-tenant architecture

# 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.

<Note>
  This approach provides strong data isolation guarantees while still allowing for efficient resource sharing and cross-tenant operations when needed.
</Note>

## Tenant Context

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

<CodeGroup>
  ```javascript Request with Tenant Context theme={null}
  fetch('https://api.productflo.io/products', {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'X-Tenant-ID': 'tenant-123'
    }
  })
  ```

  ```python Python Example theme={null}
  import requests

  response = requests.get(
      'https://api.productflo.io/products',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'X-Tenant-ID': 'tenant-123'
      }
  )
  ```
</CodeGroup>

## Tenant Management

The following endpoints are available for managing tenants:

<Card title="POST /tenant/create" icon="plus" iconType="duotone">
  Create a new tenant (organization)
</Card>

<Card title="GET /tenants" icon="building" iconType="duotone">
  List all tenants the authenticated user has access to
</Card>

<Card title="GET /tenant/{tenant_id}" icon="circle-info" iconType="duotone">
  Get details about a specific tenant
</Card>

<Card title="PUT /tenant/{tenant_id}" icon="pen" iconType="duotone">
  Update tenant settings
</Card>

## 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

<Warning>
  Always explicitly set the tenant context when making API requests to avoid unintended cross-tenant data access.
</Warning>

## Cross-Tenant Operations

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

<CodeGroup>
  ```javascript Cross-Tenant Request theme={null}
  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'
    })
  })
  ```
</CodeGroup>

## Tenant Data Model

Each tenant has the following structure:

```json theme={null}
{
  "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