Organization Models for API Management Platforms — An Identity Perspective

Effective Identity Management for API Marketplaces

7 min readJul 27, 2020

Introduction

The concept of “API Marketplaces” and “API federation” across ecosystems have really taken the world by storm. An API Management platform should support configuring all of these API Marketplace patterns [1]. In many of these patterns, there are requirements to configure and manage “organizations” within the API Management platform.

Identity Management is an inherent requirement of API Management; hence true API Marketplaces and API Federation cannot exist without Identity Management and Identity Federation. Therefore Identity Management is also required to support “organizations”.

From an identity perspective, an “organization” is a logical representation of a set of identities (users or groups), other organization entities, and their associated entities such roles, entitlements and applications, which allows for ease of administration through delegated identity management.

There are 3 main functions regarding Identity Management in an API Management platform:

API publishing
API consumption
Application consumption

If we are to analyze the application of organizations by considering all 3 functions above, as there are too many possible combinations, it becomes overly complicated. Therefore for the ease of comprehension we will analyze the application of organizations individually for the 3 functions.

For the sake of completeness and clarity I will also include the models which don’t require organizations.

Organization Models for API Publishers

API publishers are typically the users who would design and publish APIs. With regard to organization models for API publishers, the following models exist:

APIs are created and published by one single team in the enterprise, hence there is no requirement for organizations for API publishers.
APIs are created and published by multiple teams in the enterprise, hence each team will be represented as an organization in the API Management platform. This is known as an “Internal API Marketplace” [1].
APIs are created and published by multiple legal entities, hence each legal entity will be represented as an organization in the API Management platform. This type of marketplaces are collectively known as “External API Marketplaces”. “Partner API Marketplaces”, “Closed-group API Marketplaces”, “Shared-Revenue API Marketplaces” and “Aggregator Marketplaces” belong to this category.
An API Management platform-as-a-service (PaaS) solution where each new domain that is registered in the platform is represented as an organization.

Sometimes internal teams can comprise of external users such as consultants who could also publish APIs. Also in Public API Marketplaces typically external parties such as partners or other enterprises may publish APIs. Typically these users are managed in one of the following ways:

Provisioning local accounts
Federated identity management [2]

Organization Models for API Consumers

API consumers are typically the users who would subscribe to the APIs, in order to consume them and develop applications. With regard to organization models for API consumers, the following models exist:

APIs are consumed by one single team in the enterprise, hence there is no requirement for organizations for API consumers. The applications that are developed in this model may be be used for internal or external consumption.
APIs are consumed by multiple teams in the enterprise, hence each team will be represented as an organization in the API Management platform. The APIs that are consumed in this model, may be published either by one single team for the entire enterprise, or each team may publish and consume its own APIs, or it may be that APIs are published and consumed across multiple teams. The latter category is collectively known as an “Enterprise API Marketplace”. The applications that are developed in this model may be be used for internal or external consumption. Both “Internal API Marketplaces” and “Partner API Marketplaces” belong to this category.
APIs are consumed by multiple legal entities, hence each legal entity will be represented as an organization in the API Management platform. “External API Marketplaces” belong to this category.
An API Management PaaS solution where each new domain that is registered in the platform is represented as an organization. APIs are published and consumed within an organization.

Similar to API Publishers, if there are requirements for external consultants to consume APIs or external parties such as partners or other enterprises to consume APIs, we would go about by provisioning local accounts or setting up Federated Identity Management [2].

Organization Models for Application Consumers

Application consumers are the end-users who would consume an application that in turn consumes APIs. Application consumers may consume one or more applications from an enterprise. The applications themselves may be developed by one or more teams, each of whom may be represented as an organization. With regard to organization models for application consumers, the following models exist:

Applications for workforce. There is no requirement for organizations for the application consumers because, they all are managed as part of the workforce of the particular enterprise.
Applications for B2C. There is no requirement for organizations for the application consumers because, they all are managed as part of the end consumers of the particular enterprise.
Applications for B2B. Applications are consumed by multiple legal entities, hence each legal entity will be represented as an organization.
B2B or B2C applications for designated lines-of-businesses. In this case each line-of-business may be represented as an organization. Application consumers are provisioned into an organization with respect to the line-of-business they are interacting with. Therefore the application consumers will be typically consuming only applications that are provisioned in their respective organizations.
An API Management PaaS solution where each new domain that is registered in the platform is represented as an organization. Application consumers are part of the same organization as their respective API consumers and API publishers.

If application consumers consist of external users in the case of B2B or B2C relationships, typically they are managed in one of the following ways:

Provisioning local accounts
Federated identity management / Social login for B2C [3]
Trusted subsystem [4]

In B2B, we may also encounter the requirement for “hierarchical organization management”.

As a result of following an organization model, in addition to the standard IAM benefits such as organization specific authentication mechanisms, access control rules, etc., you may also get benefits such as throttling/rate limiting, API analytics and monetization on a per organization basis. You may also get benefits such as organization wise branding for the end-user facing portals, etc. as non-functional benefits.

Real World Example

To understand the above variations further, let us look at a real world example. To make it even more interesting, let’s make it complicated by considering an enterprise-level PaaS where multiple teams are collaborating.

Let’s consider a company who is a technology provider in the BFSI sector, who builds innovative solutions to help overcome complex business challenges for mortgage and home equity lending and servicing. At the highest level of this company there are multiple business units such as mortgage, home equity, real estate and capital market/government. Within each of these business units there are multiple divisions. For example, in mortgage you have origination, servicing, default, etc. In real estate you have multiple listing services, title, etc. Each division handles a set of products and/or services. For example, the servicing division handles loan servicing, loss mitigation, bankruptcy, foreclosure, claims, invoicing, etc. Each product and/or service consists of a set of primitive functions. For example, loan servicing has a function for doing payments.

Figure 1: API Taxonomy in a BFSI technology provider company

If you model the above taxonomy to an API Management platform, the bottom-most layer which consists of primitive functions like payments corresponds to in fact APIs — a fundamental element in an API Management platform. For example, “Payment” is a fundamental resource and its corresponding actions such as “post”, “read”, etc. could make up the API. The “Payment” API is part of “Loan Servicing” API product. An API product is a packaging of APIs that makes it easier to manage and subscribe to APIs. The “Loan Servicing” product is handled by the “Servicing” division which corresponds to an organization. The “Servicing” division functions under the “Mortgage” business unit, which also corresponds to an organization, which means there is a hierarchy of organizations.

The company may have its own 1st party applications developed for its users. There can be multiple application development teams, each team corresponding to a division in the business. Each team corresponds to an organization in the API Management platform. There can be partners of this company who also develop 3rd party applications. Those partners may also be required to be part of this API Management platform, hence each partner needs to be provisioned their own organization in the API Management platform, and preferably setup identity federation with their own company identity provider.

The company may be servicing multiple corporate customers and each customer may need to have their own organization in the API Management platform. It may be required to have delegated administration set up, so that the corporate customer may designate their own administrators to manage their respective users and their access rights for the applications.

In the above scenario, organizations are needed for all 3 segments of users in the API Management platform, i.e. for API publishers, API consumers and application consumers. This scenario is a typical example of an enterprise API marketplace.

WSO2 API Manager Limitation

The WSO2 API Manager comes with built-in support for organizations which is also called multi-tenancy across the WSO2 platform. One of the current limitations in WSO2 API Manager is that, in organization models (2) and (3) for API consumers, you cannot register a single physical application as one logical application across multiple tenants to consume their respective APIs. This means that one application consuming APIs across multiple organizations will have to have multiple pairs of client credentials.

WSO2 Identity Server Limitation

One of the current limitations in the WSO2 Identity Server is that, in organization model (4) for application consumers, you cannot manage a hierarchy of organizations. However, there are ways to extend the capabilities of WSO2 Identity Server to support a hierarchy that suits the business use case.

Summary

In this post I’ve talked about the various organization models that need to be supported by an API Management platform from an identity perspective, for varying business use cases. WSO2 API Manager and WSO2 Identity Server are two industry-leading free and open source API Management and Identity & Access Management products respectively, released under the most business friendly Apache 2.0 license, which have a wide range of features to support organizations out-of-the-box, and a variety of extensibility options to support all of the organization models that I’ve discussed in this post.