Platform As A Service With Multi-Tenanted Projects

Multi-tenancy in Form.io means your SaaS customers can each have their own forms, their own submission data, their own authentication providers, and their own API endpoints, all running on a single Form.io deployment. This is not shared access to a common form library. Instead it follows the plaform as a service model where each tenant operates as an independent sub-project with complete data isolation from other tenants.

The practical outcome: you can build a SaaS product where your customers use a single application you build to create and manage their own forms (with drag and drop), and those customers never see each other’s forms or data. Form.io handles the tenant separation at the infrastructure level.

How Form.io Multi-Tenancy Works

Form.io implements multi-tenancy through a parent-child project hierarchy. You create a Parent Project that serves as the template and management hub. Each tenant becomes a sub-project under that parent, inheriting the parent’s structure but maintaining independent data.

Each tenant receives:

  • A unique API endpoint (https://yourserver.com/tenant-name/)
  • Independent form definitions (copied from the parent at creation, then independently editable)
  • Isolated submission data (Tenant A cannot query Tenant B’s submissions)
  • Separate authentication configuration (each tenant can use different OAuth providers)
  • Independent file storage settings
  • Separate roles and permissions

The parent project defines the starting template. When you create a new tenant, Form.io copies the forms and resources from a stage you specify. The tenant then operates independently. Changes to the parent do not propagate to existing tenants. Changes within one tenant do not affect other tenants.

This is documented in detail in the Multi-Tenancy documentation.

Tenant Isolation: What Is Actually Separated

Understanding what Form.io isolates between tenants is essential for security planning and compliance discussions.

Fully isolated per tenant:

  • Form schemas (each tenant has their own copy)
  • Submission data (stored with tenant-scoped identifiers)
  • API endpoints (different URL paths per tenant)
  • File storage connections (can point to different S3 buckets or Azure containers)
  • Public configuration settings (per-tenant CSS, logos, custom settings)

Shared across tenants in the standard deployment:

  • The Form.io API server (single deployment serves all tenants)
  • The MongoDB database cluster (tenant data is logically separated, not physically separated)
  • The CORS configuration (all tenants must share the parent project’s CORS settings)
  • Enterprise license utilization (tenants count against your license allocation)

What this means for compliance: Form.io’s multi-tenancy provides logical data separation, not physical separation. All tenant data lives in the same MongoDB cluster, separated via API.

If your compliance requirements mandate physically separate databases per customer, that feature is on our roadmap. The standard production environment remains responsible for form management and storing form definitions while data submissions for individual tenants are processed and stored remotely by the App Servers.

The Parent Project Acts as a Template

When you create a tenant, you specify which stage of the parent project to copy. This creates a starting point for the new tenant’s forms and resources.

The typical workflow:

  1. Build your “template” forms in the parent project’s Live or a designated Template stage
  2. Configure the parent project with default roles, actions, and settings
  3. When onboarding a new customer, create a tenant and select the template stage
  4. Form.io copies all forms, resources, roles, and actions to the new tenant

This is useful for SaaS applications where every customer starts with the same base forms but may need to customize fields, validation rules, or conditional logic for their specific needs.

The copy is a snapshot, not a sync. After tenant creation, the tenant’s forms are independent. If you update the parent template, existing tenants do not receive those updates. New tenants created after the update will receive the new version. This is intentional: it prevents unexpected changes to production forms that your customers have already customized.

If you need to push updates to existing tenants, Form.io APIs can be programmatically configured to do this for all tenants.

Embedding the Web Form Builder for Your Customers

Multi-tenancy will become more powerful when combined with the upcoming Enterprise Form Builder Module. This will allow you to embed a white-labeled web form builder directly in your application, letting your customers build their own forms without accessing the Form.io Developer Portal.

Here is what this architecture looks like:

  1. Your SaaS application authenticates users through your auth system
  2. Your application loads the Enterprise Form Builder, configured to point at that tenant’s API endpoint
  3. The user builds and manages forms within their tenant’s isolated environment
  4. Forms and submissions are stored under that tenant’s project, securely separated and invisible to other tenants

The web form builder can be customized so that tenants are shown only what they need. You can restrict which components are available, rename components to match your customers’ terminology, add pre-defined field configurations, and apply custom CSS. This is controlled through the Form Builder Pro interface in the Form.io portal.

This is what enables building a SaaS product on Form.io without exposing Form.io’s interface directly to your customers. Your customers see your brand, your terminology, and your component library. Form.io operates as invisible infrastructure.

Per-Tenant Configuration

Each tenant can maintain independent settings for integrations and behavior. This allows your SaaS customers to connect their own services rather than using shared connections.

Email transport: The developer team configures the SMTP transport. Tenant A’s form submission emails come from their domain. Tenant B’s emails come from their domain. See Email Integrations.

Authentication providers: OAuth, SAML, or use Form.io’s built-in authentication. This means your enterprise customers can integrate with their existing SSO while smaller customers use simpler auth. See Authentication Support.

File storage: Each tenant can point to their own S3 bucket, Azure Blob container, or other storage provider. This provides physical data separation for file uploads even when form submissions share a database. See File Storage documentation.

Public configurations: Arbitrary key-value settings that your application can read at runtime. Use these for tenant-specific CSS URLs, logo paths, or any other configuration your application needs per customer.

These configurations are set either through the Form.io portal or programmatically through the API when provisioning new tenants.

Tenant Provisioning Through the API

For SaaS applications onboarding customers automatically, you will create tenants programmatically rather than through the portal UI.

The tenant creation flow:

  1. Your application receives a new customer signup
  2. Your application calls the Form.io API to create a new tenant under your parent project
  3. Form.io copies the template forms to the new tenant
  4. Your application stores the tenant’s API endpoint and project ID
  5. Your application configures any tenant-specific settings (email, auth, storage)
  6. Your application grants appropriate users access to the tenant

This requires using the Form.io API with appropriate admin credentials. The deployment guide covers environment setup, and the API documentation covers the specific endpoints for tenant management.

Automatic tenant provisioning is the difference between “we can support 10 customers” and “we can support 10,000 customers.” Manual tenant creation through the portal does not scale.

What Multi-Tenancy Does Not Solve

Form.io multi-tenancy handles form and data isolation. It does not handle everything your SaaS application needs.

Billing and subscription management: Form.io does not track which tenants should be billed or enforce subscription limits. Your application must manage customer subscriptions, payment processing, and feature entitlements.

User management across tenants: Form.io can authenticate users within a tenant, but it does not manage which users belong to which tenants in your SaaS. Your application must maintain that mapping and route users appropriately.

Cross-tenant analytics: If you need to report across all tenants (for your internal analytics), you must query each tenant separately or maintain a separate analytics data store. Form.io’s aggregation and reporting features operate within a single project context.

Physical database isolation OOB: As noted earlier, tenants share a MongoDB cluster. If regulatory requirements mandate separate databases, you need separate Form.io deployments rather than multi-tenancy. However, it’s possible to send data to other endpoint(s), which means configuring multi-tenancy for form separation whereas data storage is somewhere else. Webhooks can be leveraged to send the data wherever you want.

Application UI and business logic: Form.io provides forms as infrastructure. Everything else about your SaaS application, including navigation, dashboards, business logic, integrations with your other services, is your responsibility to build.

Multi-tenancy is powerful infrastructure, but it is infrastructure for forms and data capture, not a complete SaaS platform. See Why Form.io Is Infrastructure, Not an App Builder for more on this distinction.

When to Use Multi-Tenancy vs. Separate Projects

Form.io offers two ways to separate customer data: multi-tenancy (sub-projects under a parent) and separate top-level projects.

Use multi-tenancy when:

  • You have many customers (dozens to thousands) who need similar form capabilities
  • Logical data separation is sufficient for your compliance needs
  • Customers need to see their own branding when they log in, even though all tenants use the same app

Use separate projects when:

  • You have a small number of large customers with very different requirements
  • Each customer needs a completely independent Form.io environment
  • Customers will access the Form.io Developer Portal directly
  • Different customers need different Form.io license tiers or features

Use separate Form.io deployments when:

  • Regulatory requirements mandate physical database separation
  • Customers require network isolation between environments
  • You are reselling Form.io to customers who will manage their own infrastructure

The multi-tenancy feature is designed for SaaS vendors serving many customers from a single deployment. If you are building an internal application for a single organization with multiple departments, multi-tenancy may still be useful, but the architecture is optimized for the SaaS use case.

Technical Requirements for Multi-Tenancy

Multi-tenancy is an Enterprise feature. It requires:

  • An Enterprise license with multi-tenancy enabled
  • A self-hosted deployment
  • MongoDB or a MongoDB-compatible database
  • Developer resources to integrate tenant routing into your application

Multi-tenancy is licensed in buckets of 10 tenants. If you need more than 10 tenants, you purchase additional tenant buckets. There is no per-tenant API call or submission fee; pricing is based on tenant count and infrastructure, not usage volume. See configuration-based pricing for details.

The development work required to implement multi-tenancy includes:

  • Building tenant provisioning logic in your application
  • Implementing user-to-tenant routing based on authentication
  • Building your own web form builder UI
  • Configuring per-tenant settings through the API
  • Handling tenant lifecycle (creation, suspension, deletion)

This is not a checkbox feature. It is infrastructure that your development team builds on. See Why You Shouldn’t Use Form.io If You Do Not Have a Dev Team for context on the technical resources required.

The Alternative: Building Multi-Tenancy Yourself

If Form.io did not provide multi-tenancy, you would need to build it yourself. That means:

  • Designing a tenant identification scheme for all forms and submissions
  • Implementing tenant filtering on every API query
  • Building access control logic to prevent cross-tenant data access
  • Creating tenant provisioning and lifecycle management
  • Building a web form builder UI that operates in tenant context
  • Handling tenant-specific configuration for email, auth, and storage

This is a significant engineering effort, typically months of work for a competent team. Form.io’s multi-tenancy provides this infrastructure out of the box, letting your team focus on your application’s unique value rather than rebuilding tenant isolation that every SaaS needs.

The tradeoff is that you are adopting Form.io’s model for multi-tenancy. If your requirements differ significantly from how Form.io structures tenants (for example, if you need cross-tenant form sharing or hierarchical tenant relationships), you may find yourself working against the system rather than with it.

Related Documentation

Related Features