Two Azure API Management topics keep coming back in platform discussions: how to give product teams their own space without buying a Premium instance per team, and how to handle custom domains when moving to the v2 tiers. Both changed recently. Since June 2026, workspaces can run on the built-in gateway in every tier except Consumption, and the certificate options for custom domains differ more between classic and v2 tiers than most teams expect. This guide covers both, with the decisions and checks I use when designing an API platform.

Workspaces in one paragraph

Workspaces let decentralized teams manage their own APIs, products and subscriptions inside a shared API Management instance, while a central platform team keeps control of the instance, networking and global policies. It is the API Management answer to federated API ownership.

What changed: workspaces on the built-in gateway

Previously, using workspaces in production meant associating them with dedicated workspace gateways, which tied the model to the Premium tiers and added cost and operations. Microsoft first announced in 2025 that it would reintroduce workspace support on the built-in gateway, and in June 2026 that became generally available. You can now:

• Use workspaces in any API Management tier except Consumption.
• Create workspaces in any region where API Management is available.
• Use built-in gateway capabilities that workspace gateways do not offer, such as multi-region deployment, custom hostnames and Private Link connectivity.

Workspaces on the built-in gateway share that gateway’s properties: hostnames, private networking, scale, protocol settings and regions. When Microsoft announced the change it published per-tier limits for workspaces on the built-in gateway – up to 30 in Premium and Premium v2, 5 in Standard and Standard v2, and 1 in Basic, Basic v2 and Developer. Check the current documentation for your tier before you design around those numbers.

Built-in gateway or workspace gateway?

My default: start with workspaces on the built-in gateway, and introduce a workspace gateway only for a team with a hard isolation requirement, such as a critical API that must not be affected by another team’s load.

One limitation to plan for: MCP server capabilities in API Management are currently not supported in workspaces. If a team wants to expose MCP servers, that happens at the service level – see MCP servers in Azure API Management.

A workspace operating model

1. Platform team owns the instance, networking, custom domains, global policies, diagnostics and the naming convention for workspaces.
2. Product teams own their workspace: APIs, products, subscriptions and workspace-level policies.
3. Policy layering – global policies enforce the non-negotiables (authentication, logging, header hygiene); workspace policies handle team-specific behaviour.
4. Deployment – each team deploys its workspace content through its own pipeline, with the platform team’s pipeline owning instance-level configuration. See APIOps CLI as a GitOps model for API Management.

Custom domains: the rules that cause outages

API Management only accepts requests whose host header matches the gateway’s default domain name or one of its configured custom domain names. The default gateway endpoint remains available after you add a custom domain. Beyond that, the details differ by tier:

• Multiple gateway hostnames are supported in the Developer and Premium tiers; support in the v2 tiers has been evolving, so verify the current documentation for Premium v2 before you design around multiple hostnames.
• Wildcard domains such as *.contoso.com are supported in Developer, Basic, Standard, Standard v2, Premium and Premium v2.
• Free managed TLS certificates are not available in the v2 tiers. In the classic tiers, creation of new managed certificates was temporarily suspended from August 15, 2025 to June 30, 2026; existing managed certificates kept renewing.
• Key Vault certificates must be stored in Key Vault as a certificate, not as a secret, and you must not delete the certificate, the key vault or the managed identity API Management uses to read it.
• Certificate pinning – if a client pins certificates, use your own certificate (custom or from Key Vault), not the default or a managed certificate.

Moving a custom domain to a v2 instance

Upgrading a classic instance in place to a v2 tier is not available, so moving to v2 means a new instance and a controlled cutover. For the domain, the sequence I use:

1. Import the certificate into Key Vault as a certificate and grant the new instance’s managed identity access.
2. Configure the custom domain on the new instance and deploy all APIs through your pipeline.
3. Test against the new instance with the production host header before touching DNS.
4. Lower the DNS TTL in advance, switch the CNAME to the new gateway, and monitor errors and latency.
5. Keep the old instance running until traffic has fully moved and clients with cached DNS are gone.

Also check network rules that reference API Management, such as service tags in NSGs and firewalls – see API Management service tag network rules.

Checklist

• Workspace model documented: who owns what, which policies are global.
• Workspace gateways only where isolation is a requirement.
• Tier limits for workspaces checked against the number of teams.
• Custom domain certificates in Key Vault as certificates, with monitored expiry.
• Host headers and DNS cutover rehearsed for v2 migrations.

Sources

• API gateway in Azure API Management (feature comparison)
• Update to API Management workspaces: built-in gateway and tiers support
• API Management v2 tiers overview
• Configure a custom domain name for API Management