Create and manage a workspace in Azure API Management

APPLIES TO: Premium

Set up a workspace to enable an API team to manage and productize their own APIs, while providing the API platform team with the tools to observe, govern, and maintain the API Management platform. After you create a workspace and assign permissions, workspace collaborators can create and manage their own APIs, products, subscriptions, and related resources.

Follow the steps in this article to:

Create an API Management workspace associated with the instance's default managed gateway, or associated with a new or existing workspace gateway.
Assign permissions to the workspace.

Prerequisites

An API Management instance. If you need one, create it in a supported tier.
Owner or Contributor role on the resource group where the API Management instance is deployed, or equivalent permissions to create resources in the resource group.

Create a workspace and associate the default managed gateway - REST API

You can create a workspace that routes API traffic through the service's default managed gateway instead of to a workspace gateway. This option avoids the extra cost and complexity of a separate gateway resource. API traffic routes through the service's default hostname (for example, <service-name>.azure-api.cn).

Note

Currently, creating a workspace and associating the default managed gateway is only supported via the API Management REST API.

Use the Workspace - Create or Update REST API to create a workspace.

PUT https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}?api-version=2024-05-01
Authorization: Bearer {token}
Content-Type: application/json

{
  "properties": {
    "displayName": "my workspace",
    "description": "Workspace using default managed gateway",
    "serveOn": "workspaceAndDefault"
  }
}

Replace:

{subscriptionId} with your Azure subscription ID
{resourceGroupName} with the resource group name of your API Management instance
{serviceName} with the name of your API Management instance
{workspaceId} with a unique workspace identifier (alphanumeric, hyphens allowed)

A successful response returns HTTP 201 Created with the workspace resource. By default, the workspace routes API traffic through the service's default hostname.

After the workspace is created, proceed to Assign users to workspace - portal to configure access permissions.

Assign users to workspace - portal

After creating a workspace, assign permissions to users to manage the workspace's resources. Each workspace user must be assigned both a service-scoped workspace RBAC role and a workspace-scoped RBAC role, or granted equivalent permissions by using custom roles.

If the workspace uses a workspace gateway resource, also assign workspace users an Azure-provided RBAC role scoped to the workspace gateway.

Note

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

For a list of built-in workspace roles, see How to use role-based access control in API Management.
For steps to assign a role, see Assign Azure roles using the portal.

Assign a service-scoped role

Sign in to the Azure portal, and go to your API Management instance.
In the left menu, select Access control (IAM) > + Add.
Assign one of the following service-scoped roles to each member of the workspace:
- API Management Service Workspace API Developer
- API Management Service Workspace API Product Manager

Assign a workspace-scoped role

In the menu for your API Management instance, under APIs, select Workspaces > the name of the workspace that you created.
In the Workspace window, select Access control (IAM) > + Add.
Assign one of the following workspace-scoped roles to the workspace members so they can manage workspace APIs and other resources:
- API Management Workspace Reader
- API Management Workspace Contributor
- API Management Workspace API Developer
- API Management Workspace API Product Manager

Assign a gateway-scoped role

Sign in to the Azure portal, and go to your API Management instance.
In the left menu, under APIs, select Workspaces > the name of your workspace.
In the left menu of the workspace, select Gateways, and select the workspace gateway.
In the left menu, select Access control (IAM) > + Add.
Assign one of the following roles to each member of the workspace. At minimum, assign the Reader role to view the gateway's settings. Owners and Contributors can manage the gateway's settings, including scaling the gateway.
- Owner
- Contributor
- Reader

Get started with your workspace

Depending on their role in the workspace, users might have permissions to create APIs, products, subscriptions, and other resources, or they might have read-only access to some or all of these resources.

To get started managing, protecting, and publishing APIs in a workspace, see the following guidance.

Resource	Guide
APIs	Tutorial: Import and publish your first API
Products	Tutorial: Create and publish a product
Subscriptions	Subscriptions in Azure API Management Create subscriptions in API Management
Policies	Tutorial: Transform and protect your API Policies in Azure API Management Set or edit API Management policies
Named values	Manage secrets using named values
Backends	Use backends in Azure API Management
Policy fragments	Reuse policy configurations in your API Management policy definitions
Schemas	Validate content
Groups	Create and use groups to manage developer accounts
Notifications	How to configure notifications and notification templates

Last updated on 2026-09-22