Skip to main content

Multi-Tenancy

What you'll learn
  • what does multi-tenancy mean
  • how Webiny helps you develop apps to support multi-tenancy
Webiny Enterprise

This is a Webiny Enterprise feature. You must have an appropriate license to use the feature. Please contact us at sales@webiny.com for more information or book a call.

Webiny Serverless CMS is designed for multi-tenancy and the framework itself provides a simple SDK to work with tenants.

In this key topic, we cover what multi-tenancy means and how it helps you to build multi-tenant applications.

What is Multi-Tenancy?#

Multi-tenancy is an architecture which allows you to serve multiple customers, called tenants, using a single instance (deployment) of your software.

Think of a SaaS (Software as a Service) application you may be using: G-Suite, Contentful, even AWS itself. These are all good examples of multi-tenant systems. You have an account (which represents a single user, or an organization), you have your collaborators, and you share some kind of data. Different collaborators have different permissions on the data. All the users of these platforms share the same code base, and it's running on the same hardware.

Multi-Tenancy in Webiny#

All Webiny apps are designed to support multi-tenancy. It is implemented as a very thin layer that sits at the very beginning of the API request lifecycle. Every HTTP request must specify a tenant it's communicating with, using the X-Tenant header. Once a request reaches the request handler, Webiny extracts the header and loads the tenant from the database.

From this point on, every storage operation (be it a database query, or a search engine query), uses the tenant ID to store and filter data specific to that particular tenant.

What if I don't use multi-tenancy?

Every Webiny project has tenancy baked in. Even if you don't need multi-tenancy, there's always a root tenant behind the scenes, and all your data is stored in a multi-tenant manner. Your custom apps, however, don't need to worry about it if you don't plan to run them in a multi-tenant environment.


Although this is all tenancy does on a high level, we need to take a quick trip into a completely separate, but still relevant topic to get the complete picture of how tenancy works.

Tenancy and User Management#

It's important to note that tenants and users are two very different concepts. A tenant can be anything: an organization, a project, a restaurant - anything that needs to have its data isolated. It very much depends on what you're developing and the specifics of your project. A tenant is a generic word that describes a unit with isolated data.

Tenants can have many users assigned to them, and each user can have different permissions when accessing different tenants. Here's a diagram that depicts this concept:

Tenancy and Users

And why is all this important? Because when authorization kicks in, we need to be able to provide permissions that an authenticated user has on the given tenant. This is all Webiny needs to work. A tenant ID and a set of permissions to be able to perform authorization and business logic checks.

Admin User Management#

Out of the box, Webiny provides an implementation of user management for Admin Area users. The implementation contains the concept of users, personal access tokens, API keys and user groups. Each user is assigned to a user group, and during authorization it is able to load the permissions that are configured for that user group.

Custom User Management#

How you manage permissions and links between users and tenants is completely up to you. Every project is very individual, and many things depend on project requirements so Webiny can't provide a generic implementation that will work for everyone. Moreover, your app can run on a different database, while default Webiny setup runs on DynamoDB.

Last updated on by Pavel Denisjuk