Skip to main content
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

SaaS Providers

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

Agencies & Consultants

Manage multiple client dashboards
  • Create separate workspaces for each client
  • Maintain consistent reporting across clients
  • Scale your analytics offering efficiently

Enterprise Organizations

Department or regional separation
  • Isolate data between business units
  • Maintain compliance and governance
  • Provide self-service analytics to different teams

Resellers & Partners

Build analytics products on Papermap
  • Create value-added analytics solutions
  • Manage customer subscriptions programmatically
  • White-label Papermap under your brand

​
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

Setup Guide

Configure multi-tenancy in your Papermap workspace

Backend Implementation

Implement secure tenant dashboard management with HMAC authentication

Tenant Usage Tracking

Track per-tenant credit consumption and API usage

Best Practices

Security, scaling, and troubleshooting guidance