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

# Multi-Tenancy Overview

Papermap's multi-tenancy feature enables you to serve multiple customers, clients, or organizations from a single Papermap instance while maintaining complete data isolation and customization for each tenant.

## Overview

Multi-tenancy in Papermap allows you to:

* **Serve multiple clients** from a single Papermap account
* **Isolate data** completely between different tenants
* **Customize branding** and theming per tenant
* **Manage permissions** at the tenant level
* **Scale efficiently** without managing separate instances
* **Control features** and access rights per tenant
* **Track usage** per tenant for billing and analytics

## What is Multi-Tenancy?

Multi-tenancy is an architecture where a single instance of Papermap serves multiple independent customers (tenants). Each tenant's data, users, and configurations are logically isolated, even though they share the same underlying infrastructure.

## Use Cases

<CardGroup cols={2}>
  <Card title="SaaS Providers" icon="building">
    Offer white-labeled analytics to your customers

    * Embed Papermap dashboards in your application with your branding
    * Each customer sees only their own data
    * Centralized management of all customer analytics
  </Card>

  <Card title="Agencies & Consultants" icon="briefcase">
    Manage multiple client dashboards

    * Create separate workspaces for each client
    * Maintain consistent reporting across clients
    * Scale your analytics offering efficiently
  </Card>

  <Card title="Enterprise Organizations" icon="building-columns">
    Department or regional separation

    * Isolate data between business units
    * Maintain compliance and governance
    * Provide self-service analytics to different teams
  </Card>

  <Card title="Resellers & Partners" icon="handshake">
    Build analytics products on Papermap

    * Create value-added analytics solutions
    * Manage customer subscriptions programmatically
    * White-label Papermap under your brand
  </Card>
</CardGroup>

## Architecture

### Tenant Isolation Model

Papermap uses dashboard-based tenant isolation within a single workspace:

```
Your Papermap Account
└── Workspace (ID: workspace-123)
    ├── Data Sources (with tenant table configured)
    ├── API Keys & Secrets
    └── Dashboards
        ├── Dashboard A (Tenant: org-abc) → Filters to tenant_id = 'org-abc'
        ├── Dashboard B (Tenant: org-def) → Filters to tenant_id = 'org-def'
        └── Dashboard C (Tenant: org-xyz) → Filters to tenant_id = 'org-xyz'
```

**How it works:**

* **One Workspace** - Your application has a single Papermap workspace
* **Multiple Dashboards** - Each tenant gets their own dashboard within that workspace
* **Automatic Filtering** - Each dashboard is automatically filtered to show only that tenant's data
* **Tenant Table** - You configure which table identifies tenants (e.g., `customers`, `organizations`)
* **Data Isolation** - Queries are automatically scoped to the tenant associated with each dashboard

### Database Structure

Your database should have a tenant identifier table and related tables:

```
Database
├── organizations (tenant table)
│   ├── id (tenant identifier)
│   ├── name
│   └── ...
├── users (direct table - has org_id)
│   ├── id
│   ├── org_id → organizations.id
│   └── ...
├── orders (direct table - has org_id)
│   ├── id
│   ├── org_id → organizations.id
│   └── ...
└── order_items (indirect table - via orders)
    ├── id
    ├── order_id → orders.id
    └── ...
```

When you configure multi-tenancy:

1. Select `organizations` as your tenant table
2. Papermap automatically identifies relationships
3. Create separate dashboards for each tenant
4. Each dashboard only shows data for that tenant

## Data Isolation

Papermap ensures complete data isolation between tenants:

* **Separate databases**: Each workspace can connect to different databases
* **Query isolation**: All queries are scoped to the workspace
* **User separation**: Users can only access their assigned workspaces
* **API key scoping**: API keys only work for their associated workspace

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup Guide" icon="sliders" href="/documentation/multi-tenancy/setup">
    Configure multi-tenancy in your Papermap workspace
  </Card>

  <Card title="Backend Implementation" icon="code" href="/documentation/multi-tenancy/backend">
    Implement secure tenant dashboard management with HMAC authentication
  </Card>

  <Card title="Tenant Usage Tracking" icon="chart-bar" href="/documentation/multi-tenancy/tenant-usage">
    Track per-tenant credit consumption and API usage
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/documentation/multi-tenancy/best-practices">
    Security, scaling, and troubleshooting guidance
  </Card>
</CardGroup>