[Article] Multitenant API Management with WSO2 API Manager

  • By Lakmali Erandi Baminiwatta
  • |
  • 28 Oct, 2015

Table of Contents

  1. Introduction
  2. What is multitenancy and why do you need it?
  3. Managing tenants in WSO2 products
  4. Multitenancy in API development
  5. Multitenancy in WSO2 API store
    • Public and tenant stores
    • Managing subscriptions among multiple tenants
    • Publishing APIs to multiple tenant stores
  6. Multitenancy in API gateway
  7. Multitenancy in API key manager
  8. Multitenancy in statistics


WSO2 API Manager is a complete solution for exposing core processes, data and services as APIs to the public. It addresses the challenges of exercising control, establishing trust and enforcing security and regulation for exposed APIs. With its multitenancy feature, organizations can collaborate and monetize their APIs across multiple entities such as departments, partners or simply between separate development groups.

What is multitenancy and why do you need it?

The goal of multi-tenancy is to maximize resource sharing among multiple tenants while providing an isolated view for each tenant.

One of the main benefits of multi-tenancy is the ability to use a single deployment for multiple tenants. By leveraging this feature you can lower your cost and provide better administration. This is ideal for multi-departmental and multi-partner business settings.

WSO2 API Manager can be deployed on-premise, on a PaaS (platform as a service) or in a hybrid environment. It provides multi-tenancy in two main deployments; multi-tenancy on the server and multi-tenancy on the Cloud.

Multitenancy on server: WSO2 API Manager enables multi-tenancy benefits in on-premise deployments with server hardware and virtualized environments such as Amazon and VMware Cloud.

Multitenancy on API Cloud: WSO2 API Manager is fully cloud ready with cloud native capabilities. It can be plugged into WSO2 Private PaaS.

This article will focus on how multi-tenant features in WSO2 API Manager can be used in on-premise deployments.

Managing tenants in WSO2 products

You can register tenant domains using the management console of WSO2 products. To add and view a tenant, follow the below steps;

  1. On the ‘Configure’ tab of the management console click on ‘Add New Tenant’ under ‘Multitenancy’.
  2. Enter the below tenant information in the ‘Register A New Organization’ and click ‘Save’;
    • Domain - the unique domain name for the organization (e.g. hr.com)
    • Usage plan for the tenant - the usage plan defines limitations for the tenant (e.g. no. of users)
    • First Name/Last Name - name of the tenant admin
    • Admin Username - the login username of the tenant admin. Username always ends with the domain name (e.g. [email protected])
    • Email - the email address of the admin
  3. The newly added tenant appears in the ‘Tenants List’. Click ‘View Tenants’ on the left menu to see information of all tenants currently existing in the system.

Multitenancy in API development

WSO2 API Manager provides a simplified Web interface called WSO2 API Publisher for API design, implementation and management. It is a structured GUI, designed for API creators to design, implement, manage, document, scale and version APIs, while also facilitating more API management related tasks such as life-cycle management, monetization, analyzing statistics, quality and usage and promoting and encouraging potential consumers and partners to adopt the API in their solutions.

While providing all these capabilities, WSO2 API Publisher is a tenant isolated application. This means that developers from different tenant domains can develop APIs and manage them while having isolated views for each tenant. Let’s look at an example scenario.

Example: There is a multi departmental organization in which three departments namely HR, sales and engineering need to expose their core functionality/services as APIs for internal and external consumption. They are using WSO2 API Manager as the API management solution, so we can consider the three departments to be three tenants. Each department can now develop and manage their APIs independently.

First we need to create three tenants in WSO2 API Manager. In the above section, we saw how to create and view tenants in WSO2 products. Let’s assume that following tenant domain names are used for each department.

Department Name Tenant Domain
Human Resource hr.com
Sales sales.com
Engineering eng.com

Figure 1: Tenant isolated API publishing for each department

Once you create the tenants, you can login to API Publisher using the tenant credentials and design, implement, manage and publish APIs. Refer to the user guide on API development for more information

Now the tenant users of each domain will have isolated views in the API publisher as shown below.

Figure 2: hr.com API publisher view

Figure 3: eng.com API publisher view

Multitenancy in WSO2 API Store

API Manager provides a structured Web interface called the WSO2 API Store to host published APIs. API consumers and partners can self-register to it on-demand to find, explore and subscribe to APIs and evaluate available resources and collaboration channels. The API store is where the interaction between potential API consumers and API providers happen. Its simplified UI reduces time and effort taken when evaluating enterprise-grade, secure, protected and authenticated API resources.

When there are multiple tenants in the API Manager deployment, there is a tenant isolated view of API store for each tenant domain. In other words there will be a separate store for each tenant.

Public and tenant stores

When the API Store URL (e.g. https://localhost:9443/store) is accessed in a multi tenant deployment, we can see the ‘Public Store’ which is a store of stores. The public store links to all the tenant stored. For anonymous users, each of these stores can be browsed and all the public APIs of each store will be visible. If the user wants to subscribe to any of the APIs they need to log into one of the stores.

Figure 4: Public store links to all the tenant stores

Each of the stores representing each tenant domain is known as a ‘Tenant Store’, which is the tenant isolated API store of each domain (e.g. https://localhost:9443/store?tenant=hr.com)

Subscribers from each tenant domain can consume APIs in their tenant store. Let’s look into more details by using an example scenario.

Example: You are a subscriber on the hr.com tenant domain. You can access the public store and visit the hr.com store. Then you can log into the store with your credentials and consume its APIs. You can also go back to the public store and access the other stores. But if you want to consume an API in other tenant stores, the API developers need to allow it. This will be discussed further in the below sections of this article.

Figure 5: hr.com tenant store

Manage subscriptions among multiple tenants

As described above, different tenants can develop and consume APIs in isolated views of the API publisher and API store. This section describes how API creators can control who can subscribe to an API. In the ‘Add API’ page, under ‘Subscriptions’, select the ‘Subscriptions’ category.

There are three subscription categories including

  1. Available to current tenant only: The API can be subscribed to by users in the current tenant domain only (tenant domain of API creator)
  2. Available to all the tenants: The API can be subscribed to by all the tenants in the deployment
  3. Available to specific tenants: The API can be subscribed to by specific tenants who are mentioned and the current tenant.

Example: UserProfileAPI is an API in hr.com. The API developer from hr.com tenant domain sets the subscription category of UserProfileAPI to sales.com and eng.com subscribers as below.

Figure 6: Subscription availability to specific tenants

Now a subscriber from eng.com can login to his API store and access the hr.com API store. He will be able to subscribe to UserProfileAPI.

Although API subscription is allowed for different tenant domains, this approach has a drawback. API subscribers need to log in to own the tenant store (eng.com), then browse the hr.com store and discover the UserProfileAPI. The next section will discuss how you can make the UserProfileAPI visible in the eng.com store.

Publishing APIs to multiple tenant stores

WSO2 API Manager allows API developers to publish APIs to external stores. By default, when a tenant user publishes an API, it gets published in that tenant’s own API store. With this WSO2 API Manager feature, each tenant can configure a set of external stores that they wish to publish their APIs to.

API developers can then push their APIs to those configured tenant stores. This allows them to expose their APIs to a wider community. However, when subscribing to such APIs, users will be redirected to the original publisher's store.

Figure 7: Publish to multiple tenant stores

We can configure external stores by following the steps below;

  1. Log in to the WSO2 API Manager management console (https://:9443/carbon) as the hr.com admin and select the ‘Browse’ menu under ‘Resources’.
  2. When the registry opens go to /_system/governance/apimgt/externalstores/external-api-stores.xml resource.
  3. Click the ‘Edit as Text’ link and change the <ExternalAPIStores> element of each external API store that you need to publish APIs to.

Example: The HR department configures external stores for sales and engineering departments as shown below so that UserProfileAPI can be pushed into sales.com and eng.com API stores.

Figure 8: External store configuration

Figure 9: External API stores in API publisher

As shown in the figure 9, the hr.com API publishers can push UserProfileAPI into the Engineering store and Sales store from the ‘External API Stores’ tab.

Example: [email protected] publishes the UserProfileAPI into the Engineering store and Sales store. When a subscriber from eng.com clicks on UserprofileAPI, there is a link to access the original store.

Figure 10: UserProfileAPI appearing in eng.com store

Figure 11: Link to publisher store (hr.com store)

Multitenancy in WSO2 API Gateway

In WSO2 API Manager, the API gateway is a simple API proxy that intercepts API requests and applies policies such as throttling and security checks. These API proxies are deployed in WSO2 API Manager as Synapse REST resources. In a multitenant deployment, APIs are deployed in a tenant isolated manner by having isolated deployment spaces for each tenant. APIs are exposed with tenant domain based URL patterns as shown below.

Example: We created UserProfileAPI in the hr.com domain and ArticleFeeds API in the eng.com domain. In the API gateway these APIs are deployed in different spaces. Also APIs are exposed with tenant domain based URLs with /t/. As shown below, the UserProfile API is exposed as https://gateway.cin/t/hr.com/userprofile/1.0.0 and the ArticleFeeds API is exposed as https://gateway.cin/t/eng.com/articlefeeds/1.0.0. Now, when application developers are consuming these APIs from different domains, they’ll see the tenant based API endpoint URLs.

Figure 12: Multi-tenancy in API gateway level

Multitenancy in WSO2 API Key Manager

The API key manager component handles all security and key related operations. When the API gateway receives API calls, it contacts the API key manager service to verify the validity of tokens and perform security checks. All tokens used for validation are based on OAuth 2.0 protocol. First API subscribers have to create an application, then subscribe to APIs and generate tokens against that application.

In a multitenant deployment, consumer applications are tenant isolated. At the API subscription and key generation, keys (consumer key/secret) are issued against these consumer applications. Then the tenant users, who consume the applications can generate user tokens. When storing keys, tenant IDs are used to achieve tenant separation. This is how multitenancy is achieved in the API key manager.

Multitenancy in statistics

We can setup WSO2 Business Activity Monitor (WSO2 BAM) to collect and analyze runtime statistics from the WSO2 API Manager. To publish data from the API manager to the business activity monitor, the Thrift protocol is used. The usage data publisher is created per tenant.

Information processed in WSO2 BAM is stored in a database from which the API publisher and store retrieves information before displaying it in the corresponding UI screens. The statistics view in API store and API publisher are tenant isolated, since API store and publisher apps are tenant isolated.

Figure 13: Multitenancy in API statistics


This article discussed how organizations can collaborate and monetize their APIs across multiple entities such as departments and partners with the multitenancy features of WSO2 API Manager. API developers of multiple entities can have isolated views in WSO2 API Publisher and manage their APIs. API consumers who correspond to multiple entities can explore and consume APIs from tenant isolated API stores.

Moreover this article described how API subscriptions can be controlled among tenants and how APIs can be published into multiple API stores. We also discussed how multitenancy is achieved in API gateway, key manager and statistics.


About Author

  • Lakmali Erandi Baminiwatta
  • Associate Technical Lead
  • WSO2