This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
![](data:image/svg+xml, %3Csvg xmlns='http://www.w3.org/2000/svg' height='64' class='font-weight-bold' style='font: 600 30.11764705882353px "SegoeUI", Arial' width='64'%3E%3Ccircle fill='hsl(182.40000000000003, 50%, 27%)' cx='32' cy='32' r='32' /%3E%3Ctext x='50%25' y='55%25' dominant-baseline='middle' text-anchor='middle' fill='%23FFF' %3ENJ%3C/text%3E%3C/svg%3E)
We're adopting Azure API Management Workspaces (Premium tier). I need a definitive answer on base path (API URL suffix) uniqueness when multiple workspaces are involved.
Scenario
Workspace A has an API with base path: /apples/api/
Workspace B (in the same APIM instance) needs to publish another API with the same base path: /apple/api/.
In Scenario 1, both workspaces would use the default/built-in gateway.
In Scenario 2, each workspace would use a separate workspace gateway (different gateway resources).
Question
What I understand so far (please confirm/correct):
Workspaces are management-plane isolation; APIs still publish through the same APIM service runtime and gateway surface.
Microsoft Learn-Workspaces in Azure API Management (overview of workspaces and workspace
gateways):
https://learn.microsoft.com/en-us/azure/api-management/workspaces-overview
The API path (URL suffix) is a unique identifier within the APIM service instance per the REST contract for creating/updating an API under a workspace:
Workspace Api-Create Or Update (see properties.path: "Relative URL, uniquely identifying this API
...within the API Management service instance.:
https://learn.microsoft.com/en-us/rest/api/apimanagement/workspace-api/create-or-update?view=rest-
Goal
apimanagement-2024-05-01
I need to give my teams a clear rule: can two workspaces (even on different workspace gateways) reuse the same base path on the same APIM instance, or is the API URL suffix globally unique across the instance?
Environment
APIM Premium (Workspaces GA)
Considering both built-in gateway and workspace gateways
CI/CD via laC (Terraform) that targets workspace resource paths
Thanks in advance for an official clarification and the precise doc reference.
An Azure service that provides a hybrid, multi-cloud management platform for APIs.
![](data:image/svg+xml, %3Csvg xmlns='http://www.w3.org/2000/svg' height='64' class='font-weight-bold' style='font: 600 30.11764705882353px "SegoeUI", Arial' width='64'%3E%3Ccircle fill='hsl(182.40000000000003, 77%, 27%)' cx='32' cy='32' r='32' /%3E%3Ctext x='50%25' y='55%25' dominant-baseline='middle' text-anchor='middle' fill='%23FFF' %3EPK%3C/text%3E%3C/svg%3E)
Hello NIDHIN JOSEPH,
There is no current or announced configuration in:
Premium
v2
Workspace GA
VNET-injected gateways
Self-hosted gateway
Scale units
that allows duplicate properties.path inside the same APIM service.
Hello NIDHIN JOSEPH,
We haven’t heard from you on the last response and was just checking back to see if you have a resolution yet. In case if you have any resolution please do share that same with the community as it can be helpful to others. Otherwise, will respond with more details and we will try to help.
Hi Praveen,
Thanks for the clarification.
We are currently evaluating the feasibility of using APIM Workspaces for a specific scenario. At the moment, one of our external vendors manages APIs in their own APIM instance. Our plan is to migrate those APIs into our organization’s APIM service.
However, instead of giving the vendor full APIM-level access, we are considering giving them workspace-level access so they can manage only their APIs while our platform team continues to manage the overall APIM infrastructure.
Given this approach, we wanted to understand the following:
If the vendor already has APIs with certain base paths in their current APIM, and we migrate them into our APIM under a dedicated workspace, would the API URL suffix uniqueness constraint across the entire APIM service prevent us from maintaining the same base paths if similar APIs already exist in other workspaces?
In other words, does this limitation reduce the feasibility of using workspaces for isolating vendor-managed APIs within a shared APIM instance?
Additionally, if maintaining identical base paths is not possible, would it be a recommended approach to differentiate APIs using versioning in the path, for example:
/api1/v1
/api1/v2
so that the API logical grouping remains similar while still satisfying the global uniqueness requirement of the API URL suffix?
Appreciate your guidance on whether this is a recommended pattern when onboarding external teams into a centralized APIM using workspaces.
Thanks in advance.
Hello NIDHIN JOSEPH,,
Yes — using path-based differentiation (such as versioning or prefixes) is a commonly recommended pattern when onboarding external teams or vendors into a centralized API platform using Azure API Management Workspaces.
Why this pattern is recommended
When multiple teams manage APIs within the same APIM instance:
The API URL suffix (path) must be globally unique across the service instance.
Workspaces provide management isolation, but they do not create separate runtime namespaces for API paths.
Therefore, some coordination of API paths is required to avoid conflicts.
Because of this design, organizations typically adopt structured naming conventions for API paths when enabling multi-team or vendor onboarding.
Common patterns used in centralized APIM platforms
This keeps APIs logically grouped while allowing evolution over time.
/api1/v1
/api1/v2
This approach is widely used and aligns with standard API versioning strategies.
Useful when multiple organizations manage APIs in the same APIM instance.
/vendor1/api1
/platform/api1
This helps maintain clear ownership boundaries while satisfying the uniqueness constraint.
Some organizations structure APIs by capability:
/payments/v1
/orders/v1
/customer/v1
This reduces collision risk when different teams onboard APIs.
When identical paths must be preserved
If the vendor must keep exactly the same public paths (because external clients already depend on them), some organizations choose to:
Host those APIs in a separate APIM instance, or
Place a front-door routing layer in front of multiple APIM services.
Summary
Using versioning or structured path conventions is a recommended and widely adopted approach when:
Multiple teams or vendors manage APIs
A centralized APIM instance is used
Workspaces provide governance boundaries
This allows you to maintain workspace-level delegation for vendors while still complying with the global path uniqueness requirement of the APIM service.
In Azure API Management (APIM), the API URL suffix (base path) must be unique across the entire APIM service instance, regardless of whether the APIs are in different workspaces or using different workspace gateways. This means that in your scenario:
In summary, the API URL suffix must be globally unique across the APIM instance, and this rule applies irrespective of the workspace or gateway configuration used.
Thank you for the clarification. I have one follow-up question to fully eliminate any ambiguity around the base-path uniqueness rule in APIM Workspaces.
Based on your response, the API URL suffix must be unique across the entire APIM instance, even when:
APIs belong to different workspaces
Each workspace is associated with a different workspace gateway
Workspace gateways are isolated with different scale units or VNET configurations
To confirm without any remaining doubt:
workspace gateway isolation
preview vs GA workspace behavior
service-level managed identity limitations
VNET-integrated workspace gateways
or any APIM tier differences
where two APls across different workspaces could legally reuse the same properties.path (API URL suffix within the same APIM instance?
Does Microsoft explicitly confirm that this uniqueness requirement applies across all workspaces and across all workspace gateways, with no exceptions?
Relevant documentation:
Workspace API-Create/Update (properties.path uniqueness):
https://learn.microsoft.com/en-us/rest/api/apimanagement/workspace-api/create-or-update?
view=rest-apimanagement-2024-05-01
Workspaces Overview (shared service-level gateway model):
https://learn.microsoft.com/en-us/azure/api-management/workspaces-overview
I want to ensure that globally unique API base paths are a strict, non-negotiable rule across all workspaces and workspace gateways, and that there is no configuration-current or upcoming would permit duplicate base paths within the same APIM instance. that
Thank you for helping clarify this fully so that we can establish correct governance rules for our internal API platform.