Release - API Management service: September, 2025

Highlights

Since the last update, we've added:

• MCP support (public preview), enabling you to expose APIs in API Management or external MCP servers as AI agent tools with stronger authentication, governance, and observability.
• Workspace support for federated logging, metrics and autoscale, and the Premium v2 tier.
• Applications (public preview), offering built-in OAuth 2.0–based access to products.

New features and improvements

• You can now enable content-safety checks on chat completions for final redaction, logging, and response validation using the enforce-on-completions attribute of the llm-content-safety policy. This setting is off by default.
• Model logging now supports the Azure OpenAI Realtime API.
• Product resource names can now include dots (.).
• Email notifications are now supported in v2 tiers.
• OpenAPI imports are now safer, result in cleaner API definitions, and fail with clearer error messages.
  • Imports are blocked if a path placeholder (e.g., /orders/{id}) has no matching parameter, with a clear validation error shown.
  • Imports from localhost URLs are now blocked. You can use file upload or an accessible non-localhost URL instead.
  • If a response object doesn't include a description, API Management now defaults it to an empty string.
• The policy engine now blocks embedding scripts using the XsltSettings.EnableScript setting.
• Policy parsing is now consistent across locales, ensuring numbers are interpreted reliably regardless of browser language or region (comma vs. dot), preventing save errors.
• The validate-azure-ad-token policy now returns more detailed error messages when token validation fails.
• API inspector now provides better visibility into authentication, showing when OAuth or OIDC settings were last refreshed, whether refresh succeeded, and any error details.
• The self-hosted gateway now produces cleaner JSON logs, applies configuration updates more reliably, and starts successfully even when the OpenTelemetry monitoring isn't configured.

Bug fixes

• Resolved issue where prolonged cache outages could cause gateway data plane downtime.

⚠️ Changes

• We are working on reintroducing support for workspaces on the gateway built into Azure API Management service, effectively rescinding parts of the previously announced breaking changes. For now, newly created workspaces are not accessible via the built-in gateway, as announced in the March 2025 breaking changes.
• API versions prior to 2019-12-01 no longer return secrets via GET operations. The Azure Policy definition enforcing a minimum API version has been deprecated. Newer API versions remain unchanged, returning secrets only through POST operations. Learn more about API version retirement.
• Generating API debug traces now requires the Microsoft.ApiManagement/service/apis/write permission to better protect sensitive data.

Self-hosted gateway

• Container image: 2.9.1
• Helm Chart: 1.13.1
• Container image: 2.9.0
• Helm Chart: 1.13.0

Release - API Management service: May, 2025

This release will be deployed gradually in phases and batches, following the safe deployment practices framework. The rollout will span several weeks across all Azure regions, so your services may not have the new features and fixes until the deployment is complete.

New Features and Improvements

Workspaces

• Workspaces are now supported in Norway East and West Europe. See the documentation for details and instructions for accessing workspaces in West Europe.
• You can now associate multiple workspaces with a single workspace gateway.

Gateway & Traffic Management

• Quota-by-key policy is now available in v2 service tiers, enabling more flexible and fine-grained rate limiting. More info.
• Circuit breaker configuration in backends now supports an optional failureResponse property, allowing you to define fallback HTTP status codes (100–599). More info.
• Data-plane events in Azure Event Grid (Public Preview) are now enabled by default in the gateway, allowing for richer event notifications and diagnostics.
• You can now configure the same URL suffix for both HTTP REST and WebSocket APIs, simplifying endpoint design.

Platform & Portal Enhancements

• Authoring API Management policies with Microsoft Copilot in Azure is now Generally Available.
• The Network Status page in the Azure Portal now displays new monitoring endpoints for national cloud regions, improving visibility into service health and diagnostics. More info.

LLM & Semantic Caching

• Launched enhanced logging for large language model (LLM) scenarios, including new fields — resourceId, workspaceId, and region — for improved traceability. Log timestamps are now emitted in date-time format instead of long integers, aligning with standard observability practices.
• Semantic caching has been updated to support GPT-4o prompts that include multiple content types and now correctly identifies max-message-count of the most recent messages.

Observability Enhancements

• The emit-metric, azure-openai-emit-token-metric , and llm-emit-token-metric policies now treat dimension keys as case-insensitive, ensuring consistent metric grouping and reducing casing-related issues.
• Backend pool failures now include a Retry-After header to support client-side resiliency strategies.
• Self-hosted gateway now emits additional debug logs, including snapshot decompression, manglers, and listeners to assist with diagnostics. More info.

---

⚠️ Changes

• You may need to associate a workspace with a workspace gateway before managing resources in that workspace. More info
• We've updated how the state of asynchronous operations is tracked in the Microsoft.ApiManagement resource provider in all API version. Going forward, responses will include an Azure-AsyncOperation header, in addition to the Location header. This header contains a URL following the format below, which can be used to monitor the operation status: https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ApiManagement/service/{service-name}/tenant/operationResults/{operation-id}. To check the status of an operation, customers using built-in roles don't need to take any action. However, custom reader roles must be updated to allow the Microsoft.ApiManagement/service/tenant/*/read action. Learn more.
• We’ve improved how capacity usage is calculated for API Management services. As a result, you may notice that reported usage appears higher than before. This change reflects a more accurate calculation method that better represents the actual utilization of your service. It should have no impact on the performance or throughput of your service.

---

Bug Fixes

Gateway & Traffic Management

• Fixed a bug where VNet-integrated Standard v2 services required blob storage access to be unblocked via NSG for management operations.
• Fixed delivery issues in log-to-eventhub policy in Basic v2 and Standard v2 SKUs.
• Fixed inaccurate detection and counting of backend connectivity errors in the Circuit Breaker policy.
• Fixed bandwidth calculation in quota-by-key policy on self-hosted gateway to include transferred bytes.

Telemetry and Monitoring

• Fixed a bug where backendTime reported in Azure Monitor and Application Insights was higher than expected.
• Resolved startup and connection failures in self-hosted gateway when telemetry or feature-flagged endpoints were not fully rolled out.
• Fixed missing WebSocket Azure Monitor logs due to lowercase resource IDs.

OpenAPI Specification Handling

• Resolved an issue where OpenAPI definition did not include a response description. If omitted, it is now auto-filled as an empty string.
• OpenAPI 'format' properties are now preserved correctly during import (previously could appear in the description).
• Required formData fields are now properly enforced.

Workspace & Product Configuration

• Fixed an issue preventing workspace deletion after failed gateway activation.
• Deleting an API Management service now requires removal of all associated workspace gateways.
• When a product is configured to limit subscriptions, the limit must now be greater than zero.

Other Reliability Improvements

• Improved reliability of the llm-content-safety policy and added support for multiple blocklists and categories.
• Import of API specifications from a localhost address is no longer supported.
• Improved formatting of error responses for management API requests that fail due to minimum API version enforcement.

Developer Portal

• 2.33.0

Self-hosted Gateway

• Container Image: 2.8.1
• Helm Chart: 1.12.1

Release - API Management service: January, 2025

This release will be deployed gradually in phases and batches, following the safe deployment practices framework. The rollout will span several weeks across all Azure regions, so your services may not have the new features and fixes until the deployment is complete.

Featured content

• Discover the latest announcements and demos in our Microsoft Ignite session "Effective API governance in the era of AI with Azure API Management".
• Watch the recording of our YouTube live stream in December, featuring deep-dives into recent features and industry developments.

New features and improvements

• Azure OpenAI token limit policy now fully supports prompts that include images.
• Azure OpenAI token limit policy and LLM token limit policies can now also enforce overall token quota.
• Backend identifier can now be used as a dimension in any of the emit metric policies.
• Workspaces are now available in the Germany West Central region.
• Synthetic GraphQL requests, especially those with large schemas or multiple complex resolvers, perform much faster now.

Bug fixes

• Requests to an API in an open product and containing a subscription key for a different product are not being rejected anymore.
• Validate content policy now works correctly with nullable properties in JSON payloads, including those defined by the oneOf, anyOf, and allOf schema constructs.
• Redirect content URLs policy doesn't add redundant slashes to the output URLs like it used to in some cases.
• Validate Entra ID token policy now correctly puts decrypted token into the context variable specified in the output-token-variable-name attribute.
• Rate limit by key policy now returns correct value in the Retry-After header in all cases.
• Array fields are now returned when included in Synthetic GraphQL subscriptions.
• You can now successfully add a workspace to a service configured with a custom hostname.

Self-hosted developer portal releases

• 2.30.0

Self-hosted gateway container image releases

• None

Self-hosted gateway Helm chart releases

• None

Release - API Management service: August, 2024

🎉 Announcements

• Workspaces are now generally available. Learn how to empower API teams and federate the management of APIs with workspaces.
• GenAI gateway capabilities are now expanded to support a wider range of large language models through Azure AI Model Inference API.
• Developer portal audit logging is now generally available.
• WordPress plugin to build customized developer portals is now in preview.
• You can watch the recording of our July live stream on YouTube. We'll be hosting another live stream in September—stay tuned to our blog for the upcoming announcement.

❗ Changes

• If an API does not require subscription authentication, any API request that includes a subscription key will now be treated the same as a request without a subscription key. Previously, if a request included a subscription key associated with a different API or product, API Management would return a 401 Unauthorized response. This change improves the security of your APIs by preventing the accidental exposure of subscription keys linked to other products. Update Sep 3, 2024: This change will be rolled out with another release.
• As part of the general availability of workspaces, we are discontinuing support for preview workspaces in API Management. You can learn more about these changes in the last section of the workspaces general availability announcement and in this documentation article.

New features

• We added support for serializing a single child XML element into a JSON array using the XML-to-JSON policy.
• We added support for case-insensitive property names comparison with the optional case-insensitive-property-names attribute in the validate-content policy. The default value is false.
• We added support for the 2024-02-01 and 2024-06-01 Azure OpenAI API versions in the azure-openai-token-limit and azure-openai-emit-token-metric policies.
• We added support for integer and integer arrays as output of Azure OpenAI embeddings calls in the azure-openai-token-limit and azure-openai-emit-token-metric policies.
• We added support for managed identity authentication for newly created backends.
• We added support for the ES256 token signing algorithm in the validate-jwt policy.

Fixes and improvements

• We fixed an issue with the retry policy not working correctly with load balancer backends.
• We fixed a bug with the backend reconnect action not working properly.
• We fixed a bug with the decrypted token not being included in a context variable when using the validate-azure-ad-token policy.
• We made the certificate-id attribute of the decryption-keys element in the validate-azure-ad-token policy optional.
• We fixed a bug that caused refresh failures for certificates in a key vault referenced within a policy fragment.
• We optimized the performance of deleting users. Previously, the operation could time out if there were thousands or more users in the API Management service.
• We fixed a bug that caused an incorrect date-time format to be returned when testing GraphQL resolvers.
• We removed internal runtime exception details from GraphQL resolver error messages.
• The developer portal delegationUrl setting now defaults to null. Previously, it defaulted to an empty string, causing payload validation errors on PUT calls to the management API.

Self-hosted developer portal releases

• 2.29.0

Self-hosted gateway container image releases

• 2.7.1
• 2.7.0

Self-hosted gateway Helm chart releases

• 1.11.0

Release - API Management service: June, 2024

New features, improvements, and changes

• HTTP/2 connections are now drained and gracefully terminated before node restarts
• We added support for decryption keys to the validate-azure-ad-token policy
• azure-openai-semantic-cache-lookup and azure-openai-semantic-cache-store policies now work in both V2 and Classic tiers.
• We've improved prompt token estimation accuracy for GPT-4 models in the azure-openai-token-limit policy
• We've made request tracing more secure and it's now available in both Classic and V2 tiers
• Now customers can use Azure portal to migrate their VNet-injected stv1 service instances to stv2

Fixes

• We fixed an issue which caused GraphQL resolver runtime errors when primitive type fileds had null value
• We fixed a bug and stopped the fields of type array-of-objects from causing GraphQL resolver runtime errors
• Expressions now work as expected for in the <audience/> elements in the validate-jwt policy
• We fixed a bug causing XML elements within Liquid templates in policy documents to be needlessly decoded
• URL properties in the Backend entity no longer accept URLs containing query parameters. We've made the change to fix a bug. Please use set-query-parameter policy and backend.credentials.query to set query parameters
• We fixed an issue preventing backend load balancing feature from working properly with retry policy

Self-hosted gateway container image releases

• 2.6.0

Self-hosted gateway Helm chart releases

• 1.10.0

Release - API Management service: May, 2024

New features, improvements, and changes

• We added support for Interface type to GraphQL resolvers.
• Customer-managed public IP is no longer required when deploying a service instance into a virtual network. Changing the subnet will remove public IP from a previously deployed service instance.

Fixes

• We now correctly import schemas from OpenAPI 3.1 specifications.
• API imports will no longer fail because of OData specification warnings. However, errors will still cause import failures.
• Liquid template and policy expressions with XML special characters, such as "<" or ">", no longer result in runtime failures.
• We did not respect the JWT specification in validate-jwt policy and did not enforce "sub" claim to be a string or URI

Self-hosted developer portal releases

• 2.27.0

Self-hosted gateway container image releases

• No new releases

Self-hosted gateway Helm chart releases

• No new releases

Release - API Management service: March 2024

‼️ Breaking changes ‼️

• On June 14, 2024, we’re introducing breaking changes to the Workspaces feature. You may have to take action to continue using workspaces beyond June 14, 2024.

New features, improvements, and changes

• We’ve introduced several new features and improvements to workspaces:
  • You can now create and manage certificates, backends, diagnostics, and loggers inside a workspace with the 2023-09-01-preview management API version.Azure portal interface will be released soon.
  • You can now use context.Workspace in policy expressions.
  • "default-workspace" is now a reserved workspace resource name.
• We now preserve the format and schema properties of the form-data parameters when importing OpenAPI APIs.
• HTTP version information will now be included in the request trace.
• We’ve added support for HS512 and RS512 algorithms in the validate-jwt policy.
• client-application-ids element is now optional in validate-azure-ad-token policy.
• We've made a couple improvements to the GraphQL support:
  • We've added support for Union Type in GraphQL resolvers
  • Arrays can now be used within the set-body policy to project the data obtained by a resolver onto the list of primitive data types specified in the GraphQL schema
• An Azure Advisor notification will be sent to customers when they inadvertantly delete the FQDN property from the public IP resource assigned to API Management.
• We've made several improvements to the VNet integration in the Standard v2 tier:
  • We will now detect if the prerequisites for VNet integration are not being met - i.e., subnet delegation and service association link, and fail the deployment faster.
  • All traffic from the VNet-integrated Standard v2 service instances to the Internet will be now routed via the integrated VNet.
  • The outbound IP will now be populated and shows its respective value.

Fixes

• We’ve resolved the issue where Azure API Management would incorrectly log requests that were rejected due to public network access is disabled. This fix ensures that logs and metrics in Azure Monitor now exclude these rejected requests when API Management is set up with a private endpoint.
• An attempt to create diagnostics in a workspace that doesn't exist will now return a 404 Not Found error. Previously, API Management returned a 500 Internal Server Error response.
• Workspace users can no longer override diagnostics settings defined for all APIs on the service level.
• Exporting APIs with empty or whitespace-only examples no longer produces an error.
• Optional string query parameters are no longer added to the API operation's URL template.
• $DevPortalUrl variable in the developer welcome email template now returns a new developer portal URL. Previously, it returned a legacy developer portal URL.
• The authenticate-certificate policy now performs a case-sensitive certificate ID validation. Previously, request processing would fail when the casing between the certificate ID in the policy and in the request didn’t match.
• We've fixed an issue preventing recovery of the soft-deleted Basic v2 and Standard v2 service instances.

Self-hosted developer portal releases

• 2.26.0

Self-hosted gateway container image releases

• 2.5.0

Self-hosted gateway Helm chart releases

• 1.9.0

Release - API Management service: February 2024

New features, improvements, and changes

• TLS 1.3 and related cipher suites are now supported.
• The validate-jwt policy now works with tokens signed PS256 signature algorithm.
• We raised the content size limit in the validate-content policy to 4MB.
• A current API revision can now be addressed using a revision-specific URL in addition to the API's base URL.

Fixes

• Self-hosted gateway using EntraID authentication to connect to the associated Azure API Management service instance are now showing heartbeats in the Azure Portal.
• We fixed the issue preventing “Scheduled Maintenance” events from being shown in the Activity log.
• The set-body policies contained within GraphQL resolver policies (see example) is now executed for streamed responses.
• The issue making resolver get incorrect values from the cache for some GraphQL requests is now fixed.
• Requests resulting in a log entry larger than 32KB, previously not logged at all, are now logged to Azure Monitor after trimming.

Developer portal releases

• No releases.

Self-hosted gateway container image releases

• 2.5.0

Self-hosted gateway Helm chart releases

• 1.9.0

Release - API Management service: December, 2023

New features, improvements, and changes

• We reserved default Workspace name for internal use. After the update, users will not be able to create Workspaces with that name.

Fixes

• We fixed an issue causing degraded performance when creating new service instance.
• We fixed an issue with DevPortalHost property not being passed correctly into the email notification template.
• We eliminated inconsistency in Security Scheme and Security Requirement objects in OpenAPI exports when performed by authenticated vs. anonymous users.

Developer portal releases

• No releases.

Self-hosted gateway container image releases

• 2.4.0
• 2.3.6

Self-hosted gateway Helm chart releases

• 1.8.0
• 1.7.6.

Release - API Management service: November, 2023

New features, improvements, and changes

• We will now provide specifics about token validation failures in validate-azure-ad-token policy in API Inspector.
• We made the password policy stronger for users creating accounts on the developer portal - e.g., it now requires using a special character. Complete password requirements will be shown on the sign-up page.
• Users now must provide their current password before changing it on the developer portal.
• Pagination controls on the developer portal now feature only the Next and Previous buttons.

Fixes

• We fixed an issue that caused tokens of logged-out developer portal users signed in via Azure AD B2C to remain valid under some circumstances.
• We fixed a regression that caused POST requests issued from the try it console on the developer portal not to work correctly.
• We fixed an issue in the Content Access Control feature of the developer portal that allowed unauthorized access to pages via direct link.

Developer portal releases

• No releases.

Self-hosted gateway container image releases

• 2.4.0
• 2.3.6

Self-hosted gateway Helm chart releases

• 1.8.0
• 1.7.6