[Article] Multi-tenant API Management with WSO2 API Manager

  • By Chamin Dias
  • 2 Aug, 2016

Table of contents

Applies To

WSO2 API Manager Version 2.0 and above
WSO2 API Manager Analytics Version 2.0 and above
WSO2 Business Process Server Version 3.5 and above


WSO2 API Manager is a fully open source solution for managing all aspects of APIs including creating, publishing, and exposing APIs to users in a secure and scalable manner. It is a production-ready API management solution that has the capability of managing all stages of the API lifecycle in a massively scalable production environment. Hence, organizations can use the multi-tenancy feature of WSO2 API Manager to manage APIs across multiple entities or departments to facilitate a more secure and isolated user experience.

Multi-tenancy and its usability

A tenant in WSO2 API Manager is a separate business level entity, such as a department, group or any other logically separable domain. The key objective of this multi-tenancy feature is to maximize resource sharing while enabling single deployment use. This enables optimized performance in deployment and provides an isolated view for each tenant in the system.

For a business with multiple departments or partners, multi-tenancy allows to minimize cost while providing better administration.

Users are able to carry out tasks, such as deploying artifacts, applying security, managing users, managing data, throttling requests, and caching responses within their tenant space, which is isolated from other tenants.

WSO2 API Manager can be deployed as a standalone server on a platform as a service (PaaS). This enables multi-tenancy on the standalone server and multi-tenancy on the PaaS. WSO2 API Cloud is one of the solutions for Cloud API management.

This article depicts how an organization can use this multi-tenancy feature in WSO2 API Manager once it’s deployed on a server.

Tenant management in WSO2 API Manager

Adding a new tenant is easy with the management console of WSO2 API Manager. Please refer to the official documentation to find details about how to create a tenant.

Figure 1: Creating a new tenant

Figure 1 shows a screenshot of how a new tenant is created.

Once the tenant is created, the tenant space can be activated or deactivated easily using the management console.

Figure 2: Listing available tenants

Figure 2 shows the screen for listing available tenants. An admin user can activate or deactivate tenants using this screen.

Users of each tenant have an isolated view of the management console.

API management with multi-tenancy

This section depicts how we can use multi-tenancy in WSO2 API Manager to manage APIs using a real-world scenario.

WSO2 API Manager allows users to control API visibility and subscription availability. API visibility can be one of the following options:

  • Public: The API is accessible to everyone and can be advertised in multiple stores - a central store and/or non-WSO2 stores.
  • Restricted by roles: The API is visible only to specific user roles in the tenant store that you specify.

Subscription availability has three options. Those options are as follows:

  • Available to current Tenant Only: Only users in the current organization/tenant domain can subscribe to the API
  • Available to All the Tenants: Users of all organizations’ tenant domains can subscribe to the API
  • Available to Specific Tenants: Users of the organizations/tenant domains you specify as well as the current tenant domain can subscribe to the API

In order to find the usability of these options, we will take a real-world example and find out how the multi-tenant feature of WSO2 API Manager can address your business requirements.

Example scenario

An organization consists of three departments. Each department has APIs to carry out their business functions. Depending on the need, visibility of the APIs need to be controlled. Some APIs should be accessible from the entire organization while some APIs should be only accessible from its respective department. At the same time, there are some APIs that should be accessible from selected departments. Table 1 contains the information about APIs deployed in each department with the respective subscription visibility.

Department Domain Name of the API Subscription accessibility
Engineering department eng.lk DeveloperAPI Only for engineering department
HR department hr.lk EmployeeDetailAPI Only for HR department
AttendanceAPI All departments
Finance department finance.lk PayrollAPI HR and Finance departments

Table 1: Details of APIs deployed in each department

Let’s explore how we can facilitate the above business requirement using WSO2 API Manager.

There should be three tenants. The domain names are eng.lk, hr.lk and finance.lk. The tenant domain should be unique. Once the tenants are created, users of each department can log into the respective tenant space and create APIs with the respective API visibility and subscription availability.

API creators can use the Publisher web interface of WSO2 API Manager to create and publish APIs. Please refer to the official documentation to discover more information about API creation in WSO2 API Manager.

The engineering department should create an API called “DeveloperAPI”. This API is only for the use of the engineering department. Hence, when creating the API, the user should specify the visibility of the API as “Visible to my domain”. This ensures that the API is only visible/subscribable by users in the engineering department. Figure 3 shows how you can set the correct visibility for “DeveloperAPI” as per the requirement.

Figure 3: Setting visibility for “DeveloperAPI” as “Visible to my domain”

“EmployeeDetailAPI” of the HR department is similar to the above case. This too should be created with “Visible to my domain”. Since “AttendanceAPI” should be accessible from all departments, it should be created with “Public” visibility. Additionally, the subscription availability of “AttendanceAPI” should be mentioned as “Available to all the tenants”.

Figure 4: Setting Visibility for “EmployeeDetailAPI” as “Visible to my domain”

Figure 5: Setting Visibility for “AttendanceAPI” as “Public”

Figure 6: Setting subscription availability for “AttendanceAPI”

The Finance department has an API called “PayrollAPI” that can be accessible from the HR and Finance departments. In this case, the API creator of the Finance department should create “PayrollAPI” with “Public” visibility and subscription availability as “Available to specific tenants” and mention the tenant domains of the HR and Finance departments.

Figure 7: Setting Visibility for “PayrollAPI” as “Public”

Figure 8: Setting subscription availability for “PayrollAPI”

Tenant users of each domain have an isolated view on API Publisher. Figure 9, 10 and 11 show the API Publisher of HR, Engineering, and Finance departments, respectively.

Figure 9: API Publisher of “hr.lk”

Figure 10: API Publisher of “eng.lk”

Figure 11: API Publisher of “finance.lk”

Figure 12: Tenant isolated view in API Publisher

WSO2 API Manager provides an enterprise-ready API Store. You can use the API Store to subscribe and test APIs. The API Store is the web interface that’s used to host published APIs. API consumers can register with the corresponding API stores (if self user sign-up is allowed) and consume the services. In a multi-tenant environment, there is a separate API Store for each tenant. This provides a tenant isolated API Store for each tenant.

When it comes to the use case mentioned in this article, the API Store will be visible in the following manner:

Figure 13: Public API Store

This is the Public API Store. This is where users can browse the available API Stores. Moreover, there is an API Store named “carbon.super” that’s allocated as the tenant space for the super tenant.

As depicted in Figure 13, API consumers can choose the corresponding API Store, log in, subscribe to the allowed APIs and invoke the APIs. As per the use case, users of each tenant will get subscription access in the following manner:

Consumers of the Engineering department can subscribe to “DeveloperAPI” in “eng.lk” API Store and “AttendanceAPI” in “hr.lk” API Store.

Figure 14: Subscription availability for consumers of Engineering department

API Store of the HR department allows its users to subscribe to “EmployeeDetailAPI” and “AttendanceAPI”. They should visit the API Store of “finance.lk” to subscribe to “PayrollAPI”.

Figure 15: Subscription availability for consumers of the HR department

Consumers of the Finance department can use “PayrollAPI” in “finance.lk” in the API Store and “AttendanceAPI” in the “hr.lk” API Store.

Figure 16: Subscription availability for consumers of Finance department

Since users have an isolated tenant space and API Store per tenant, it ensures isolated API management over separate departments.

Security, key management and gateway operations in a multi-tenant environment

The key manager component in WSO2 API Manager is responsible for handling all the security aspects of the deployment. When consumers invoke APIs via API Gateway, API key manager performs token validation and authenticates the request. Key manager uses the OAuth2 protocol to grant access to API resources.

Consumers should create an application via the corresponding API Store and generate keys against the application to invoke APIs.

In a multi-tenant environment, user applications are tenant isolated. Tokens that are generated against the application are stored in the database under the corresponding application. Tenant IDs are used when storing records related to keys, so it ensures the tenant isolated in key management.

API Gateway is used to handle API requests and to apply various policies related to API usage. Since WSO2 API Manager provides isolated tenant space per each tenant, APIs are exposed with the gateway-specific URLs while supporting gateway management in the multi-tenant environment. Service URLs of APIs are constructed with the tenant domain to identify them uniquely.

External API stores in a multi-tenant environment

By default, when an API is published, it will be published to the API Store of the same tenant domain. WSO2 API Manager provides a mechanism to publish APIs to multiple external API stores. This will facilitate organizations to expose their APIs to external parties with minimum effort. An external API Store is used as an API advertising portal.

Figure 17: Publishing APIs to the default API Store and external API Stores

Example: If the HR department wants to publish an API named “EngineerPayScaleAPI”, API creators of that API need to publish it to the API store of the Engineering department. This enables consumers of the Engineering department to discover “EngineerPayScaleAPI” within their local API Store space. If users of the Engineering department are interested in consuming these APIs, they need to visit the API Store of the HR Department and subscribe.

API statistics with multi-tenancy

With WSO2 API Manager Analytics 2.0.0, users can view API related statistics. Mainly the statistic model has Publisher and Store related statistics. Users need to configure API Manager analytics and they will be able to view API statistics in API Publisher and API Store.

Published APIs Over Time, API Usage, API Response Times, API Last Access Times, Usage by Resource Path and Usage by Destination are a few of the statistics that are visualized in WSO2 API Manager.

Figure 18: Some statistics in API Publisher

Figure 19: Some statistics in API Store

Once API Manager Analytics is configured correctly, statistics related to each tenant will be displayed in each tenant space in an isolated manner.

Workflow extensions and configuring workflows for tenants

In real-world scenarios, organizations might need to enable human task involvement in order to complete a task related to API usage. At the same time, different departments within the same organization might need human approval tasks for different operations. For example, in the HR department, users need to obtain approval from a senior employee to create an application when they need to consume an API. At the same time, users in the Finance department are allowed to create applications based on their wish, but they should have a human approval task involved when generating an access token to consume the APIs. These kind of business requirements can also be facilitated using WSO2 API Manager 2.0 and WSO2 Business Process Server 3.5.1. Please refer to the official documentation to find out how to configure workflows for tenants.


This article focused on how multi-tenancy of WSO2 API Manager can be used in organizations to facilitate business requirements related to API management. Since WSO2 API Manager is a complete, enterprise-ready solution for managing APIs across the complete API lifecycle, organizations can use it to manage APIs in a multi-tenant environment with ease.

Moreover, this article depicted how multi-tenancy can be achieved in API Publisher, API Store, API Key Manager and API Gateway. It further described usability of multi-tenancy, publishing APIs to external tenant stores, viewing API-related statistics in a multi-tenant environment, and workflow extensions in a multi-tenant environment with the related concepts.

About Author

  • Chamin Dias
  • Senior Software Engineer
  • WSO2