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

1

Log in to Papermap

Navigate to papermap.ai and sign in with your credentials.
2

Navigate to your workspace

Select the workspace where you want to enable multi-tenancy.
3

Open Settings

Click on Settings in the drop-down options on the workspace card to access workspace configuration.
Click on Settings In the settings editor, find Multi-Tenant on the sidebar and click it to open the configuration page. Select Multi-Tenant

​
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.
1

View available tables

In the Multi-Tenant configuration page, you’ll see a list of available tables from your connected data sources.
2

Choose your tenant table

Find the table you want to use as your tenant identifier (e.g., customers, organizations, users).
3

Set as tenant table

Click Use as Tenant on your chosen table.
Select Tenant Table
In this example, we’re using the organization table as our tenant identifier.

​
Step 3: Understanding Table Categories

You will be redirected to the Tenant Table Configuration page. This page allows you to control which tables each tenant can access. Tenant Table Configuration

​
Table Categories Explained

Tables that are directly related to the tenant table (contain a foreign key to the tenant table).Examples:
  • Tables with customer_id, tenant_id, or organization_id columns
  • User accounts, orders, transactions
Behavior: Automatically filtered based on the tenant context.
Tables related to the tenant through other tables (connected through join relationships).Examples:
  • order_items table (if orders is a direct table)
  • Nested relationships through multiple joins
Behavior: Filtered per tenant through intermediate relationships.
Tables accessible to all tenants without filtering.Examples:
  • Product catalogs
  • Country/region reference data
  • System configuration
  • Lookup tables
Behavior: Data is not filtered by tenant - accessible to all.
Tables that should not be accessible to any tenant users.Examples:
  • Internal admin tables
  • Audit logs
  • System metadata
  • Billing information
Behavior: Completely hidden from tenant users.

​
Step 4: Organize Your Tables

Now organize your tables into the appropriate categories based on your security and data isolation requirements.
1

Review table categories

Examine which tables Papermap has automatically categorized based on foreign key relationships.
2

Move tables as needed

Drag and drop tables to different categories, or use the move/assign options in the interface.
3

Secure sensitive data

Move any tables you don’t want tenants to access to the Excluded Tables section.
4

Configure shared resources

Ensure shared reference tables are in the Shared Tables section.
5

Verify tenant isolation

Confirm that tenant-specific data tables are in Direct Tables or Indirect Tables.
Moving Tables - Example 1
Quick Reference for Table Organization:
  • Direct Tables: Tables with customer_id, tenant_id, or organization_id
  • Indirect Tables: orders → order_items (if orders is direct, order_items is indirect)
  • Shared Tables: Product catalogs, country/region reference data
  • Excluded Tables: Internal admin tables, audit logs, system metadata
In this example, all tables are in the Direct Tables category.

​
Step 5: Create API Keys

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

Save configuration

Click Configure as Tenant Table to save your table organization.
2

Navigate to API Keys

Go back to Settings → API Keys.
3

Generate new key

Click Create API Key to generate credentials.
4

Save credentials

Copy and securely store both the API Key and Secret.
Create API Keys
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.

​
Step 6: Complete Configuration

Your multi-tenancy setup is now complete!

​
What Happens Next?

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

Data Isolation

Each tenant only sees data from Direct and Indirect tables that belong to them.

Shared Access

Shared tables remain accessible to all tenants for common reference data.

Security

Excluded tables are completely hidden from tenant users.

Automatic Filtering

Queries are automatically scoped to the tenant context.

​
Next Steps

Backend Implementation

Implement secure tenant dashboard management with HMAC authentication

Tenant Management

Learn how to manage tenant lifecycles and operations

​
Troubleshooting Setup

  • 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
  • Verify foreign key relationships in your database
  • Manually move tables to the correct categories
  • Check table relationships in your data source
  • Ensure you have administrative permissions
  • Check that you saved the tenant table configuration first
  • Try refreshing the page and generating again