Multi-Tenant Setup in PandaDoc

Organizations integrating PandaDoc often need to accommodate multiple user groups from different department, locations, functions, or even from different companies, while maintaining data security, access control, and efficient document management.
It is especially important for organizations that resell PandaDoc to multiple companies.

A multi-tenant setup allows different independent groups or clients to use PandaDoc within a single organization while ensuring proper segregation of documents, templates, and other resources.
We will call a group of users sharing the organization a Tenant.

Structuring a Multi-Tenant Setup

To implement a multi-tenant architecture in PandaDoc, it is essential to determine how tenant-specific data will be organized and managed. Two primary approaches are commonly used:

Creating a Separate Workspace for Each Tenant – Each tenant has a dedicated workspace, providing strict isolation and customized settings.
Using Folders Within a Single Workspace – Tenant data is organized into folders within a shared workspace, relying on folder-level permissions to control access.

Workspaces vs. Folders: A Comparative Analysis

Each approach has its advantages and trade-offs. The table below highlights key considerations:

Aspect	Workspaces (Per Tenant)	Folders (Within Single Workspace)
Data Segregation	Complete isolation of tenant-specific documents, templates, and contacts within dedicated workspaces.	Data is organized in folders but resides within a shared workspace, requiring careful management of access controls.
User Access Control	Users are assigned to specific workspaces, restricting access to only their tenant’s data. Roles define granular permissions within each workspace.	Permissions are managed at the folder level, but automating role-based access might be complex.
Branding and Customization	Each workspace supports independent branding, email settings, and integrations, enabling a tailored experience for tenants.	A single set of branding and settings applies to all tenants, limiting customization options to template-level adjustments.

Managing Templates and Documents Across Workspaces

When using multiple workspaces, it is necessary to consider how templates and other entities are shared and managed.

Sharing Templates and Content Library Items

Administrators can share templates and content library items between workspaces.
Shared content appears in the "Shared with me" folder in the recipient workspace.
Limitations:
- Shared templates are read-only in the recipient workspace. To modify them, edits must be made in the original workspace.
- If a template contains smart content blocks, these will not be visible in the recipient workspace and will not be cloned with a template.

Sharing Documents and Templates between Workspaces

Documents cannot be moved between workspaces directly.
To transfer a document, it must be downloaded and re-uploaded to the desired workspace, resetting its status to "Draft."
Templates can be shared, but modifications must be made in the original workspace.

Automating Workspace Provisioning with the PandaDoc API

For organizations that require automated workspace management, the PandaDoc API provides endpoints to create and manage workspaces programmatically.

Creating a Workspace

A new workspace can be created using the API.
The API key must belong to an Organization Admin.
The Org Admin is automatically added as the first Admin user in the new workspace.
API Endpoint: POST /public/v1/workspaces
Documentation: Create Workspace

Generating an API Key for a Workspace

API keys are issued at the workspace level.
A key-to-workspace mapping must be maintained for proper access control.
The key’s permissions and limits are defined by the key’s owner.
API Endpoint: POST /public/v1/workspaces/{workspace_id}/api-keys
Documentation: Create API Key

Adding Members to a Workspace

Existing users can be added to a workspace via the "Add Member to Workspace" API.
Only Organization Admins or Workspace Admins can assign members.
API Endpoint: POST /public/v1/workspaces/{workspace_id}/members
Documentation: Add Member to Workspace
Alternatively, the Create User endpoint can be used to add a new user to both an organization and a workspace.

For further details on available API operations, refer to the PandaDoc API Reference.

Choosing the Best Multi-Tenant Structure

For most organizations, creating a separate workspace for each tenant provides the most effective solution, ensuring clear data segregation, access control, and the ability to customize settings per tenant. While managing multiple workspaces requires additional administrative effort, the benefits in security outweigh the complexities.

However, for organizations with fewer tenants or minimal customization needs, using folders within a shared workspace may be a simpler alternative. Evaluating your organization’s size, security requirements, and administrative resources will help determine the most suitable approach.

To learn more about Workspace management, refer to the official PandaDoc Workspaces Documentation.