Azure API Management workspaces demystified!

Recently, the Azure API Management team announced a new feature called Workspaces.  This purpose of this blog is to explain what is does and how you might take benefit of this.

The architecture

The main architecture of Azure API Management consists of three components:

  • The developer portal: used by the API consumers to discover API capabilities
  • The management plane: used by the API publishers to expose their APIs
  • The API gateway: the runtime infrastructure that handles all API traffic

The workspaces feature is situated purely on the management plane.  This means that all APIs across the different workspaces share the same developer portal and shared the same compute resources.

The main features


The main reason for introducing workspaces, is that multiple teams can publish APIs without interfering each other.  Resources in a workspace can reference other resources within the same workspace.  References to other workspaces are not possible.  References to service-level resources like named values and backends are not allowed, except for products, tags and users.


Azure API Management has the ability to execute policies on different scopes.  When you use workspaces, you get an additional scope where you can configure policies that are applicable for all APIs associated with that workspace.  Please be aware of the fact that policy execution highly depends on the <base/> element, as described in this blog post.


On a workspace, you can configure role assignments.  For a workspace, the following RBAC roles make sense:

  • API Management Workspace Contributor: can manage the workspace and view, but not modify its members.
  • API Management Workspace Reader: has read-only access to entities in the workspace.
  • API Management Workspace API Developer: has read access to entities in the workspace and read and write access to entities for editing APIs.
  • API Management Workspace API Product Manager: has read access to entities in the workspace and read and write access to entities for publishing APIs.

The main limitations


This feature is still in public preview, so not all resource types are supported within a workspace.  You can find the latest status over here.


Because the workspaces share the same API gateway, the technical references to other resources (e.g. named values) should be unique across the complete API Management instance.  Some examples are:

  • The API Name must be unique
  • The API URL Suffix must be unique
  • The named value name must be unique
  • The product id must be unique

Validations are in place to ensure that these restrictions on uniqueness are respected.  It’s highly recommended to agree on a dedicated naming prefix per workspace, to avoid naming clashes.

Shared infrastructure

While you have full logical isolation at design time, please do not forget that there is no physical isolation at runtime.  All APIs run on the same API gateway.


This is a highly requested feature for Azure API Management.  It has the most value in a distributed organization, where different business areas / teams have their own way of publishing APIs.  Thanks to workspaces, these teams can work independently from each other, while optimizing the costs.  In this scenario, it is highly recommended that one central team takes ownership of monitoring the infrastructure.   Autoscaling based in the Capacity metric is also advised, as described over here.

One important decision you have to take is whether you will share a Global policy across all workspaces or if you will ignore that level.  This depends if you want to have standardization across your workspaces or not.

Looking forward to see this become generally available!



Your Azure Coach is specialized in organizing Azure trainings that are infused with real-life experience. All our coaches are active consultants, who are very passionate and who love to share their Azure expertise with you.