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

Step-by-step guide to configure multi-tenancy in your Papermap workspace, including tenant table selection and API key generation. This guide walks you through configuring multi-tenancy in your Papermap workspace. Follow these steps to set up tenant isolation and data access controls.

## Prerequisites

Before you begin, ensure you have:

* A Papermap account with workspace access
* Connected data sources with tenant-identifiable tables
* Administrative permissions in your workspace

## Configuration Steps

### Step 1: Access Workspace Settings

<Steps>
  <Step title="Log in to Papermap">
    Navigate to [papermap.ai](https://www.papermap.ai) and sign in with your credentials.
  </Step>

  <Step title="Navigate to your workspace">
    Select the workspace where you want to enable multi-tenancy.
  </Step>

  <Step title="Open Settings">
    Click on **Settings** in the drop-down options on the workspace card to access workspace configuration.
  </Step>
</Steps>

<img src="https://mintcdn.com/papermap/5ySfzVNP5LqP9c9N/documentation/multi-tenancy/images/1.png?fit=max&auto=format&n=5ySfzVNP5LqP9c9N&q=85&s=ed24cc83cff474ccac6acac4d8262651" alt="Click on Settings" width="5120" height="2880" data-path="documentation/multi-tenancy/images/1.png" />

In the settings editor, find **Multi-Tenant** on the sidebar and click it to open the configuration page and then click the **Get Started** button.

<img src="https://mintcdn.com/papermap/MaXaSA_7HHtZm04W/documentation/multi-tenancy/images/5.png?fit=max&auto=format&n=MaXaSA_7HHtZm04W&q=85&s=d54a1a308580d9f28e7b258d6c52fab2" alt="Select Multi-Tenant" width="5120" height="2880" data-path="documentation/multi-tenancy/images/5.png" />

### Step 2: Select Your Tenant Table

The tenant table is the core table that identifies and separates your different tenants. This could be a `customers`, `organizations`, or `users` table - depending on your data model.

<Steps>
  <Step title="View available tables">
    In the Multi-Tenant configuration page, you'll see a list of available tables from your connected data sources.
  </Step>

  <Step title="Choose your tenant table">
    Find the table you want to use as your tenant identifier (e.g., `customers`, `organizations`, `users`).
  </Step>

  <Step title="Set as tenant table">
    Click **Use as Tenant** on your chosen table.
  </Step>
</Steps>

<img src="https://mintcdn.com/papermap/5ySfzVNP5LqP9c9N/documentation/multi-tenancy/images/3.png?fit=max&auto=format&n=5ySfzVNP5LqP9c9N&q=85&s=9cd3bb58cfff904772459945c6fdcb1d" alt="Select Tenant Table" width="5120" height="2880" data-path="documentation/multi-tenancy/images/3.png" />

<Info>
  In this example, we're using the `organization` table as our tenant identifier.
</Info>

### Step 3: Understand and Organize Your Tables

You will be redirected to the **Tenant Table Configuration** page. Papermap automatically analyzes your schema and sorts every table into one of three categories based on how it relates to the tenant table.

<img src="https://mintcdn.com/papermap/cfwCJd2rUw12S_c2/documentation/multi-tenancy/images/4.png?fit=max&auto=format&n=cfwCJd2rUw12S_c2&q=85&s=6286271ce3150beb151bbe83f8ac2218" alt="Tenant Table Configuration" width="5120" height="2880" data-path="documentation/multi-tenancy/images/4.png" />

At the top of the page you'll find:

* **Tenant identifier column** — the column on the tenant table (usually the primary key) that the tenant id from API requests will be compared against.
* **Re-run Analysis** — re-runs the auto-categorization. Use this after schema changes.
* **Enabled** toggle — turns multi-tenant enforcement on or off for this workspace.

#### Table Categories Explained

<AccordionGroup>
  <Accordion title="Tenant Data" icon="shield-check">
    Tables whose rows are filtered to the active tenant on every query.

    Papermap fills this category in two ways:

    * **Direct filter** — the table contains a column that points to the tenant table (e.g. `tailor.organizationid`). Filtering is applied directly.
    * **Join path** — the table has no direct tenant column, so a chain of joins is used to reach the tenant id. You define this chain using the path builder (see Step 4).

    **Examples:** user accounts, orders, transactions, dashboards, anything tenant-owned.
  </Accordion>

  <Accordion title="Shared Data" icon="globe">
    Tables that can be read by every tenant without filtering.

    **Examples:**

    * Product catalogs
    * Country / region reference data
    * System configuration
    * Lookup tables
  </Accordion>

  <Accordion title="Blocked Data" icon="ban">
    Tables that cannot be queried at all in tenant mode.

    **Examples:**

    * Auth tables (`users`, `sso_providers`, `mfa_factors`, `refresh_tokens`)
    * Audit logs and system metadata
    * Internal admin or billing tables
  </Accordion>
</AccordionGroup>

#### Organize Your Tables

Review the auto-categorization and adjust anything that doesn't match your security requirements.

<Steps>
  <Step title="Review categories">
    Check which tables Papermap placed in **Tenant Data**, **Shared Data**, and **Blocked Data**.
  </Step>

  <Step title="Move tables as needed">
    Drag and drop tables between the three columns to override the automatic placement.
  </Step>

  <Step title="Secure sensitive data">
    Move anything tenants should never see (admin tables, audit logs, billing) into **Blocked Data**.
  </Step>

  <Step title="Mark shared resources">
    Put catalogs, lookups, and reference tables into **Shared Data** so they remain readable across tenants.
  </Step>

  <Step title="Save">
    Click **Save Tenant Policies** at the bottom of the page.
  </Step>
</Steps>

<Tip>
  **Quick Reference:**

  * **Tenant Data**: any table with tenant-owned rows — direct foreign key or reachable via a join path
  * **Shared Data**: product catalogs, country/region reference data, lookups
  * **Blocked Data**: auth tables, audit logs, system metadata, billing
</Tip>

<Info>
  In this example, business tables sit in **Tenant Data** while auth and system tables are auto-placed in **Blocked Data**.
</Info>

### Step 4: Define a Tenant Access Path (when needed)

Some tables in **Tenant Data** don't contain the tenant id directly. For these, you need to tell Papermap how to reach the tenant id by joining through one or more other tables.

<Steps>
  <Step title="Open the path builder">
    On the table card in **Tenant Data**, click the join/path icon in the top-right corner. The **Tenant Access Path** modal opens.
  </Step>

  <Step title="Configure Join 1">
    Set the four fields under **Join 1**:

    * **Starting table for this join** — the table you're configuring.
    * **Table it joins to** — the next table in the path toward the tenant table.
    * **Column on \<table>** — the column on the starting table used for the join.
    * **Matching column on the joined table** — the column on the joined table that matches.
  </Step>

  <Step title="Add more joins if needed">
    Click **+ Add Join Table** for multi-hop paths (e.g. `order_items` → `orders` → `organization`). Repeat the four fields for each hop.
  </Step>

  <Step title="Set the tenant id location">
    Under **Tenant id location**, choose the table and column at the end of the path that hold the actual tenant id.
  </Step>

  <Step title="Save the path">
    Click **Save Path**. The card now shows the resolved filter rule.
  </Step>
</Steps>

<img src="https://mintcdn.com/papermap/MaXaSA_7HHtZm04W/documentation/multi-tenancy/images/4b.png?fit=max&auto=format&n=MaXaSA_7HHtZm04W&q=85&s=47d4538547e8093477daa602515c0014" alt="Tenant Access Path" width="5120" height="2880" data-path="documentation/multi-tenancy/images/4b.png" />

<Tip>
  Use the path builder only when auto-analysis cannot infer a path. Tables with a direct foreign key to the tenant table are detected automatically and need no join configuration.
</Tip>

### Step 5: Create API Keys

After organizing your tables, create API keys for tenant access.

<Steps>
  <Step title="Save configuration">
    Click **Configure as Tenant Table** to save your table organization.
  </Step>

  <Step title="Navigate to API Keys">
    Go back to **Settings** → **API Keys**.
  </Step>

  <Step title="Generate new key">
    Click **Create API Key** to generate credentials.
  </Step>

  <Step title="Save credentials">
    Copy and securely store both the **API Key** and **Secret**.
  </Step>
</Steps>

<img src="https://mintcdn.com/papermap/5ySfzVNP5LqP9c9N/documentation/multi-tenancy/images/7.png?fit=max&auto=format&n=5ySfzVNP5LqP9c9N&q=85&s=6bce40ba7baac34bad6dd3e83559e6a4" alt="Create API Keys" width="5120" height="2880" data-path="documentation/multi-tenancy/images/7.png" />

<Warning>
  **Important:** Save both the API Key and Secret securely. The Secret will only be shown once and cannot be retrieved later. Store it in a secure location like a password manager or secrets management system.
</Warning>

### Step 6: Complete Configuration

Your multi-tenancy setup is now complete!

## What Happens Next?

Once configured, your multi-tenant environment will operate as follows:

<CardGroup cols={2}>
  <Card title="Data Isolation" icon="lock">
    Each tenant only sees rows from **Tenant Data** tables that belong to them — whether filtered by a direct column or resolved through a join path.
  </Card>

  <Card title="Shared Access" icon="share">
    **Shared Data** tables remain accessible to all tenants for common reference data.
  </Card>

  <Card title="Security" icon="shield">
    **Blocked Data** tables are completely hidden from tenant queries.
  </Card>

  <Card title="Automatic Filtering" icon="filter">
    Queries are automatically scoped to the tenant context.
  </Card>
</CardGroup>

## Next Steps

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

  <Card title="Tenant Management" icon="users-gear" href="/documentation/multi-tenancy/management">
    Learn how to manage tenant lifecycles and operations
  </Card>
</CardGroup>

## Troubleshooting Setup

<AccordionGroup>
  <Accordion title="Can't find my tenant table">
    * Ensure your data source is properly connected
    * Verify the table exists and has the expected schema
    * Check that you have read permissions on the table
  </Accordion>

  <Accordion title="Tables not categorizing correctly">
    * Verify foreign key relationships in your database
    * Manually move tables to the correct categories
    * Check table relationships in your data source
  </Accordion>

  <Accordion title="API key generation failed">
    * Ensure you have administrative permissions
    * Check that you saved the tenant table configuration first
    * Try refreshing the page and generating again
  </Accordion>
</AccordionGroup>