Multi-Tenant Setup in PandaDoc
How to decide what setup to use if you're embedding PandaDoc for your users or employees from multiple locations or departments
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.
Updated 7 days ago