Understanding Organizations, Workspaces, and API Keys

Organizations and workspaces

When you sign up for PandaDoc, you either create a new Organization or join an existing one.

An Organization is the top-level entity. It manages billing, subscriptions, licenses, custom roles, and SSO. Within an organization you create Workspaces to isolate data.

A Workspace contains documents, templates, contacts, and other entities. Users can belong to multiple workspaces, each with a different role. A user's effective permissions come from the combination of their organization-level license and their workspace-level role.

Organization
├── Workspace A
│   ├── Documents, templates, contacts
│   └── Users (with workspace-specific roles)
├── Workspace B
│   └── ...
└── Organization-level settings
    (billing, licenses, SSO, custom roles)

How API keys relate to workspaces

Most API operations target entities within a single workspace. Because of this:

An API key is issued at the workspace level and can only access entities in that workspace.
The only exception is when the key belongs to an Organization Admin and is used for organization-level operations (e.g., Create Workspace, Create User).

API key ownership

The API key inherits the owner's permissions, so choosing the right owner matters.

Permissions and role

The key operates with the owner's role and permissions in the workspace. The owner must have an Admin role at the time of key creation, but if their role changes later, the key's permission scope changes too. See Account Roles.

Action attribution

All API actions are executed on behalf of the key owner and appear in audit logs under their name. Choose an owner whose activity makes sense in reports.

Key deactivation

If the owner is removed from the workspace, the API key is automatically deactivated. This is the biggest risk of using a personal account as the key owner.

Rate limits

API rate limits are per user. If the same user owns keys across multiple workspaces, the rate limit is shared across all of them. Distribute key ownership to avoid hitting limits.

Best practices

Use dedicated service accounts instead of individual users, so the key owner is never accidentally removed.
Isolate Org Admin keys. For organization-level operations, create a service workspace where only the Org Admin is a member. Each key owned by an Org Admin has access to User and Workspace Management endpoints -- avoid making the Org Admin the key owner in every workspace.
Rotate keys periodically to maintain security.
Map keys to workspaces. Maintain a key-to-workspace mapping so you always know which key accesses which workspace.

Understanding Multi-Tenant Setup -- how to structure workspaces for multiple tenants
Understanding Document and Template Folders -- organizing content within a workspace
PandaDoc Workspaces Documentation