Multitenancy
Multitenancy lets you serve multiple tenants from one Workflow Engine deployment. Physical tenancy uses a dedicated database or database schema, while logical tenancy separates tenants by TenantId in a shared database and schema. Hybrid tenancy combines both storage models. The request header or default selects a tenant ID, and the request snapshot resolves its runtime and provider while Data API and RPC API operations stay in that context.
Without multitenancy, every customer or business unit needs its own deployment of Workflow Engine - its own application, its own database, its own monitoring. That model becomes expensive and hard to operate as you add customers. Every new client means provisioning another environment, applying another set of upgrades, and managing another set of backups.
Multitenancy lets a single Workflow Engine deployment serve many customers or business units (tenants) from one application instance. Tenant separation works at two levels:
- Physical tenancy - each tenant uses a dedicated database or database schema. This creates a persistence storage boundary for the tenant.
- Logical tenancy - tenants share the same database and schema. Tenant-aware persistence records are isolated by
TenantId. Suitable for multi-division enterprise deployments where operational simplicity is more important than physical database separation.
The Workflow Engine Web API supports physical, logical, and hybrid tenancy. It uses the selected tenant ID to route each request to the configured runtime and provider.
With multitenancy, you can add new customers without duplicating infrastructure. For example, a SaaS document approval platform can host workflows for dozens of client organizations from one application - each client gets isolated data, but the operations team manages a single deployment.
What it is
Multitenancy is like a storage facility. Physical tenants use separate locked rooms (dedicated databases or schemas). Logical tenants share one room and identify their records with separate labels (TenantId). A hybrid model gives some tenants private rooms while other tenants share a room.
The tenant identifier is a string value set when a process instance is created:
var createParams = new CreateInstanceParams{ SchemeCode = "OrderApproval", TenantId = "acme-corp", IdentityId = "user-42"};await runtime.CreateInstanceAsync(createParams);The TenantId is stored as a system parameter on every process instance. It is automatically propagated to subprocesses and persisted with tenant-aware process data, including statuses, parameters, timers, transition history, inbox entries, and approval history.
Workflow Engine Web API uses the selected logical tenant ID for Data API filtering and strict RPC API validation. A process from another logical tenant is not exposed to the caller. The tenant header selects context; API permissions separately determine whether the caller may access that tenant.
Physical tenancy storage
Physical tenancy gives each tenant a dedicated database or database schema. In the HTTP API layer, an IWorkflowTenant routes requests to a WorkflowRuntime and data provider configured for that storage boundary. The IWorkflowTenantLocator resolves the registration for each request based on the Workflow-Api-Tenant-ID HTTP header and the request-scoped tenant snapshot.
The header name is defined as the constant WorkflowApiConstants.TenantIdHeader. A request without the header is rejected with WorkflowTenantIdNotProvidedException (unless a default tenant is configured).
// Program.cs - configure tenants with separate databasesbuilder.Services.AddWorkflowApiCore(options =>{ options.DefaultTenantId = null; // Require header on every request});builder.Services.AddWorkflowTenants( new WorkflowTenantCreationOptions { TenantIds = ["acme-corp"], ConnectionString = "Server=db-acme;Database=Workflow;...", PersistenceProviderId = PersistenceProviderId.Mssql }, new WorkflowTenantCreationOptions { TenantIds = ["globex"], ConnectionString = "Server=db-globex;Database=Workflow;...", PersistenceProviderId = PersistenceProviderId.Mssql });Each IWorkflowTenant holds one WorkflowRuntime, one IDataProvider, and one or more logical tenant IDs. The snapshot maps every logical ID to that routing registration, and the locator resolves the mapping for each HTTP request. A dedicated database or schema configured for the registration's provider creates a physical tenancy boundary. To use schema-per-tenant isolation, configure a different DataProviderCreationOptions.DatabaseSchema for each tenant storage boundary.
Multiple runtime instances connected to the same database and schema form a Multi-Server deployment for horizontal scaling. Every instance uses the same tenant set for that shared storage boundary.
Logical tenancy (Core runtime and HTTP API)
In the logical model, multiple tenant IDs share the same database and schema. Core operations use the TenantId parameter on CreateInstanceParams and tenant-aware persistence records for data isolation. In each Workflow Engine Web API host, list the same IDs in one WorkflowTenantCreationOptions.TenantIds array. Requests for those IDs resolve to the host's IWorkflowTenant. The selected ID scopes Data API and RPC API operations. A Multi-Server deployment creates a runtime instance on each node. Every node connected to the shared storage serves the same tenant set. Your action and rule code can read processInstance.TenantId to make tenant-specific decisions:
public async Task ExecuteActionAsync(string name, ProcessInstance process, WorkflowRuntime runtime, string parameter, CancellationToken token){ var tenantId = process.TenantId; // Use tenantId to load tenant-specific configuration}Hybrid tenancy (HTTP API)
Hybrid tenancy combines dedicated and shared persistence boundaries in one Workflow Engine Web API host. Configure it by passing multiple WorkflowTenantCreationOptions entries to AddWorkflowTenants(). An entry with a dedicated database or schema represents Physical Tenancy. An entry whose TenantIds share one database and schema represents Logical Tenancy:
// Physical: acme-corp has its own database and runtime// Logical: globex and stark share a database with TenantId filteringbuilder.Services.AddWorkflowTenants( new WorkflowTenantCreationOptions { TenantIds = ["acme-corp"], ConnectionString = "Server=db-acme;...", PersistenceProviderId = PersistenceProviderId.Mssql }, new WorkflowTenantCreationOptions { TenantIds = ["globex", "stark"], ConnectionString = "Server=db-shared;...", PersistenceProviderId = PersistenceProviderId.Mssql });Why it matters
Multitenancy delivers these outcomes:
- Lower infrastructure cost per customer - A single application server handles all tenants. You do not provision separate application infrastructure for each customer.
- Faster customer onboarding - Adding a logical tenant means configuring a tenant identifier in shared storage. A physical tenant also needs a dedicated database or schema. Both models avoid provisioning another application deployment.
- Centralized operations - One application to deploy and monitor, one set of upgrades to apply. Operations teams manage one system, not one per customer.
- Flexible isolation model - Choose physical isolation with dedicated databases or schemas, logical isolation in shared storage, or a hybrid model for different customer tiers in one API host.
- Data separation at the persistence level - Physical tenants use dedicated databases or schemas. For logical tenants, Data API queries use the selected
TenantId, and RPC API operations validate the process tenant.
Who it is for
Evaluator (CEO, CTO, PM): Multitenancy is the infrastructure that lets you offer process automation as a SaaS product. It reduces per-customer cost, simplifies operations, and removes the architectural barrier to adding new clients. Choose physical tenancy for regulated industries that require storage-level separation, or logical tenancy for internal multi-division deployments.
Developer: Configure one or more tenant identifiers for each runtime and data provider. In the HTTP API, use the Workflow-Api-Tenant-ID header to select a logical tenant. In the core runtime, set TenantId on CreateInstanceParams. Read processInstance.TenantId in actions and rules for tenant-specific behavior.
Enterprise architect: Physical tenancy gives a tenant a dedicated database or schema. Logical tenancy stores multiple tenant IDs in one database and schema with TenantId filtering. Hybrid tenancy combines both storage models. One runtime instance uses Single-Server Mode; multiple coordinated runtime instances use Multi-Server Mode.
When to use it
Use multitenancy when your business model requires data separation between customers or business units but you want operational efficiency from a shared deployment. Typical examples:
- SaaS process automation platform - You host approval workflows, document reviews, or compliance processes for multiple client organizations from a single application. Physical tenancy gives selected clients a dedicated database or schema, while logical tenancy keeps other clients isolated in shared storage.
- Multi-division enterprise deployment - A single enterprise runs Workflow Engine for HR, finance, and operations. Each division has isolated data, and regulatory requirements demand data separation between divisions. Logical tenancy with
TenantIdfiltering is usually sufficient. - ISV embedding workflows - Your product ships with embedded workflow capabilities. Each of your customers runs their own workflows in isolation, but you manage one deployment rather than one per customer.
How it compares
There are four approaches to tenant separation. The table below shows the tradeoffs.
| Approach | What it requires | Result |
|---|---|---|
| Separate deployment per tenant | Provision, monitor, and maintain one full application and database per customer | High infrastructure cost, complex operations, slower onboarding |
| Workflow Engine logical tenancy | Multiple tenant IDs share one database and schema. | Lower cost, centralized management, tenant-aware data filtered by TenantId |
| Workflow Engine physical tenancy | One application deployment gives each tenant a dedicated database or schema. | Storage-level isolation with per-tenant placement control |
| Workflow Engine hybrid tenancy | Some tenants use dedicated databases or schemas while others share one database and schema. | Different isolation levels for different customer or regulatory requirements |
The key tradeoff is operational complexity vs. isolation strength. Separate deployments give full independence (including per-tenant application versions) and require corresponding operational overhead. Logical tenants use a shared database and schema with the TenantId filter. Physical tenants use dedicated databases or schemas. Hybrid tenancy applies either storage model within one API host.
See also
Workflow Engine Editions
Which editions include multitenancy and what each edition provides.
Pluggable Security
How permissions and access control work across the Workflow Engine API.
Frequently asked questions
Does multitenancy require a specific license?
Yes. Multitenancy requires a Workflow Engine NEO license that enables the multitenancy feature. See Workflow Engine Editions for licensing details.
How does the API identify which tenant a request belongs to?
The HTTP API reads the Workflow-Api-Tenant-ID HTTP header on each request, or uses DefaultTenantId when the header is absent. The request snapshot first uses this value to resolve the physical tenant (IWorkflowTenant) and select its WorkflowRuntime and data provider. The API then uses the same value as the logical TenantId that scopes Data API and RPC API operations. If neither the header nor a default value is available, the API returns an error.
Can a tenant access another tenant's processes if they know the process ID?
In physical tenancy, each tenant uses a dedicated database or schema. In logical and hybrid tenancy, Data API operations filter by the selected tenant ID and RPC API operations validate the process tenant. A process from another tenant is returned as not found rather than exposed to the caller.
How does multitenancy affect backups and restores?
In the physical model, a separate tenant database can be backed up and restored independently. Schema-per-tenant backup and restore behavior depends on the database product and tooling. In the logical model, tenants share a database and schema, so restoring that storage affects the shared tenant group. Hybrid tenancy follows the backup behavior of each storage boundary.
What happens to running instances when I add a new tenant?
Adding a new tenant is a registry change. Register a new IWorkflowTenant, or create one from WorkflowTenantCreationOptions with one or more logical IDs. The registry publishes a new immutable snapshot for new requests; existing requests keep their previous snapshot until they complete.
How does TenantId propagate to subprocesses?
TenantId is a system parameter with MergeIntoParentProcessIsProhibited = true. It is carried forward when a subprocess is created from the parent, but when the subprocess merges back, the parent's TenantId is not overwritten. This ensures the tenant identity is preserved throughout the process tree.
Can I control which users can access which tenants?
Yes. The HTTP API includes a granular permission system. Use IWorkflowApiPermissions.BuildClaim(...) and IWorkflowApiPermissionsBuilder to configure tenant-level rules: AllowAllTenants(), DenyAllTenants(), AllowAllTenantsExcept(...), or DenyAllTenantsExcept(...). API authorization checks both operation and tenant permissions on every secured request.