Workspaces in Azure API Management

  • Article

Availability

Important

This feature is available only in the Premium tier of API Management.

In API Management, workspaces allow decentralized API development teams to manage and productize their own APIs, while a central API platform team maintains the API Management infrastructure. Each workspace contains APIs, products, subscriptions, and related entities that are accessible only to the workspace collaborators. Access is controlled through Azure role-based access control (RBAC).

Note

Example scenario overview

An organization that manages APIs using Azure API Management may have multiple development teams that develop, define, maintain, and productize different sets of APIs. Workspaces allow these teams to use API Management to manage and access their APIs separately, and independently of managing the service infrastructure.

The following is a sample workflow for creating and using a workspace.

  1. A central API platform team that manages the API Management instance creates a workspace and assigns permissions to workspace collaborators using RBAC roles - for example, permissions to create or read resources in the workspace.

  2. A central API platform team uses DevOps tools to create a DevOps pipeline for APIs in that workspace.

  3. Workspace members develop, publish, productize, and maintain APIs in the workspace.

  4. The central API platform team manages the infrastructure of the service, such as network connectivity, monitoring, resiliency, and enforcement of all-APIs policies.

Workspace features

The following resources can be managed in the workspaces preview.

APIs and policies

  • Create and manage APIs and API operations, including API version sets, API revisions, and API policies.

  • Apply a policy for all APIs in a workspace.

  • Describe APIs with tags from the workspace level.

  • Define named values, policy fragments, and schemas for request and response validation for use in workspace-scoped policies.

Note

In a workspace, policy scopes are as follows: All APIs (service) > All APIs (workspace) > Product > API > API operation

Users and groups

  • Organize users (from the service level) into groups in a workspace.

Products and subscriptions

  • Publish APIs with products. APIs in a workspace can only be part of a workspace-level product. Visibility can be configured based on user membership in a workspace-level or a service-level group.

  • Manage access to APIs with subscriptions. Subscriptions requested to an API or product within a workspace are created in that workspace.

  • Publish APIs and products with the developer portal.

  • Manage administrative email notifications related to resources in the workspace.

RBAC roles

Azure RBAC is used to configure workspace collaborators' permissions to read and edit entities in the workspace. For a list of roles, see How to use role-based access control in API Management.

Workspace members must be assigned both a service-scoped role and a workspace-scoped role, or granted equivalent permissions using custom roles. The service-scoped role enables referencing certain service-level resources from workspace-level resources. For example, organize a user into a workspace-level group to control API and product visibility.

Note

For easier management, set up Microsoft Entra groups to assign workspace permissions to multiple users.

Workspaces and other API Management features

  • Infrastructure features - API Management platform infrastructure features are managed on the service level only, not at the workspace level. These features include:

    • Private network connectivity

    • API gateways, including scaling, locations, and self-hosted gateways

  • Resource references - Resources in a workspace can reference other resources in the workspace and users from the service level. They can't reference resources from another workspace.

    For security reasons, it's not possible to reference service-level resources from workspace-level policies (for example, named values) or by resource names, such as backend-id in the set-backend-service policy.

  • Developer portal - Workspaces are an administrative concept and aren't surfaced as such to developer portal consumers, including through the developer portal UI and the underlying API. However, APIs and products can be published from a workspace to the developer portal. Because of this, any resource that's used by the developer portal (for example, an API, product, tag, or subscription) needs to have a unique Azure resource name in the service. There can't be any resources of the same type and with the same Azure resource name in the same workspace, in other workspaces, or on the service level.

  • Deleting a workspace - Deleting a workspace deletes all its child resources (APIs, products, and so on).

Preview limitations

The following resources aren't currently supported in workspaces:

  • Authorization servers (credential providers in credential manager)

  • Authorizations (connections to credential providers in credential manager)

  • Backends

  • Client certificates

  • Current DevOps tooling for API Management

  • Diagnostics

  • Loggers

  • Synthetic GraphQL APIs

  • User-assigned managed identity

Therefore, the following sample scenarios aren't currently supported in workspaces:

  • Monitoring APIs with workspace-specific configuration

  • Managing API backends and importing APIs from Azure services

  • Validating client certificates

  • Using the credential manager (formerly called authorizations) feature

  • Specifying API authorization server information (for example, for the developer portal)

  • Publishing workspace APIs to self-hosted gateways

Important

All resources in an API Management service need to have unique names, even if they are located in different workspaces.

Related content