azure-api-management

name	azure-api-management
description	Expert knowledge for Azure API Management development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when securing APIM gateways, integrating LLM/backends, configuring policies/VNet, or deploying self-hosted gateways, and other Azure API Management related development tasks. Not for Azure App Service (use azure-app-service), Azure Functions (use azure-functions), Azure Logic Apps (use azure-logic-apps), Azure Web Application Firewall (use azure-web-application-firewall).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-08-09","generator":"docs2skills/1.0.0"}

Azure API Management Skill

This skill provides expert guidance for Azure API Management. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Lines	Description
Troubleshooting	L37-L45	Diagnosing and fixing APIM issues: policies and error handling, request tracing/debugging, custom domain/Key Vault cert failures, SNAT timeouts, portal problems, and using Diagnose and Solve.
Best Practices	L46-L55	Best practices for caching, throttling, security (OWASP API Top 10), SSE setup, and running the self-hosted gateway on Kubernetes in production for Azure API Management.
Decision Making	L56-L74	Guidance for planning and migrating API Management: pricing and scaling, cost control, DevOps/CI/CD, VNet choices, workspace and portal changes, and moving from legacy or other platforms.
Architecture & Design Patterns	L75-L81	Patterns for placing API Management behind App Gateway/WAF, Azure Front Door, or AKS, including routing, security, and high‑availability reference architectures.
Limits & Quotas	L82-L100	Limits, quotas, and validation rules in API Management: service and gateway limits, request/concurrency caps, LLM token quotas, SOAP/WSDL/WebSocket constraints, and validate-* policies.
Security	L101-L144	Securing APIs and gateways: auth (OAuth, JWT, Entra, B2C, certs, basic), RBAC and identities, TLS/ciphers, policies, private networking, DDoS/Defender, and secure developer portal/self-hosted gateway.
Configuration	L145-L242	Configuring APIM behavior: policies, caching, domains, networking/VNet, gateways, monitoring/metrics, developer portal, subscriptions/users, and integration with external services.
Integrations & Coding Patterns	L243-L274	Patterns and samples for integrating API Management with LLMs, backends, logging/monitoring, events, OAuth, GitHub, Dapr, and exporting/importing APIs via OpenAPI, Postman, and Power Platform
Deployment	L275-L294	Deploying and scaling API Management: multi-region, autoscale, backup/restore, migration, vNet and self-hosted gateways (AKS, Docker, Arc), portal automation, and certificate lifecycle.

Troubleshooting

Topic	URL
Trace and debug API requests in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-api-inspector
Fix API Management custom domain failures with Key Vault certificates	https://learn.microsoft.com/en-us/azure/api-management/api-management-troubleshoot-cannot-add-custom-domain
Developer portal FAQ and troubleshooting for API Management	https://learn.microsoft.com/en-us/azure/api-management/developer-portal-faq
Use Diagnose and Solve Problems for Azure API Management APIs	https://learn.microsoft.com/en-us/azure/api-management/diagnose-solve-problems
Troubleshoot SNAT port exhaustion and timeouts in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/troubleshoot-response-timeout-and-errors

Best Practices

Topic	URL
Configure response caching for APIs in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-cache
Implement custom key-based caching in API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-sample-cache-by-key
Implement flexible throttling policies in API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-sample-flexible-throttling
Run API Management self-hosted gateway on Kubernetes in production	https://learn.microsoft.com/en-us/azure/api-management/how-to-self-hosted-gateway-on-kubernetes-in-production
Configure server-sent events for Azure API Management APIs	https://learn.microsoft.com/en-us/azure/api-management/how-to-server-sent-events
Mitigate OWASP API Top 10 threats with API Management	https://learn.microsoft.com/en-us/azure/api-management/mitigate-owasp-api-threats

Decision Making

Topic	URL
Use API Management capacity metrics to plan scaling	https://learn.microsoft.com/en-us/azure/api-management/api-management-capacity
Compare Azure API Management pricing tiers by features	https://learn.microsoft.com/en-us/azure/api-management/api-management-features
Transition from built-in API Management analytics dashboard to Azure Monitor	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/analytics-dashboard-retirement-march-2027
Migrate Azure API Management ARM API versions before retirement	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/api-version-retirement-sep-2023
Migrate from direct management API to ARM-based API in API Management	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/direct-management-api-retirement-march-2025
Move from built-in Git configuration to APIOps for API Management	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/git-configuration-retirement-march-2025
Migrate from legacy to new API Management developer portal	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/legacy-portal-retirement-oct-2023
Handle breaking changes for API Management workspaces (June 2024)	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/workspaces-breaking-changes-june-2024
Migrate preview API Management workspaces to GA workspaces	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/workspaces-breaking-changes-march-2025

Architecture & Design Patterns

Topic	URL
Front internal API Management with Application Gateway and WAF	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-integrate-internal-vnet-appgateway
Use API Management with AKS microservices architectures	https://learn.microsoft.com/en-us/azure/api-management/api-management-kubernetes
Front Azure API Management with Azure Front Door	https://learn.microsoft.com/en-us/azure/api-management/front-door-api-management

Limits & Quotas

Topic	URL
API format support restrictions for OpenAPI, WSDL, and WADL	https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions
Understand Azure API Management limits and behaviors	https://learn.microsoft.com/en-us/azure/api-management/api-management-faq
Import SOAP APIs and handle WSDL restrictions in API Management	https://learn.microsoft.com/en-us/azure/api-management/import-soap-api
Limit concurrent request execution in API Management	https://learn.microsoft.com/en-us/azure/api-management/limit-concurrency-policy
Enforce LLM token limits with llm-token-limit policy	https://learn.microsoft.com/en-us/azure/api-management/llm-token-limit-policy
Configure quota-by-key policy for per-key limits	https://learn.microsoft.com/en-us/azure/api-management/quota-by-key-policy
Configure quota policy for call and bandwidth limits	https://learn.microsoft.com/en-us/azure/api-management/quota-policy
Import and convert SOAP APIs to REST in API Management	https://learn.microsoft.com/en-us/azure/api-management/restify-soap-api
Understand support policies and limitations for self-hosted gateway	https://learn.microsoft.com/en-us/azure/api-management/self-hosted-gateway-support-policies
Understand and work within Azure API Management service limits	https://learn.microsoft.com/en-us/azure/api-management/service-limits
Validate request and response bodies with validate-content policy	https://learn.microsoft.com/en-us/azure/api-management/validate-content-policy

Security

Topic	URL
Configure private networking for AI Gateway tier	https://learn.microsoft.com/en-us/azure/api-management/ai-gateway-configure-private-networking
Configure governance and security for AI Gateway tier	https://learn.microsoft.com/en-us/azure/api-management/ai-gateway-govern-secure-assets
Configure authentication and authorization for LLM APIs in API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-authenticate-authorize-ai-apis
Authorize API Management developer portal with Microsoft Entra ID	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-aad
Configure API Management developer portal with Azure AD B2C	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-aad-b2c
Add and manage custom CA certificates in API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-ca-certificates
Manage API Management developer access using groups	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-create-groups
Configure TLS protocols and cipher suites in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-manage-protocols-ciphers
Configure mutual TLS client certificates in API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-mutual-certificates
Secure API Management front-end access with client certificate authentication	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-mutual-certificates-for-clients

Configuration

Topic	URL
Configure error handling policies in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-error-handling-policies
Configure external Redis-compatible cache for API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-cache-external
Configure custom domain names for self-hosted gateway	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-configure-custom-domain-gateway
Configure notifications and email templates in API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-configure-notifications
Create and manage user accounts in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-create-or-invite-developers
Create and configure subscriptions in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-create-subscriptions
Retrieve and manage Azure API Management IP addresses	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-ip-addresses
Configure and apply Azure API Management policies	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-policies
Configure named values in Azure API Management policies	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-properties
Configure delegation for user registration and subscriptions in API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-setup-delegation

Integrations & Coding Patterns

Topic	URL
Azure PowerShell sample scripts for Azure services	https://github.com/Azure/azure-docs-powershell-samples
Import Amazon Bedrock LLM passthrough APIs into API Management	https://learn.microsoft.com/en-us/azure/api-management/amazon-bedrock-passthrough-llm-api
Integrate Azure API Management with Application Insights logging	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-app-insights
Send Azure API Management logs to Event Hubs	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-log-event-hubs
Send messages to Azure Service Bus from API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-send-service-bus
Log API Management traffic to Event Hubs and Moesif	https://learn.microsoft.com/en-us/azure/api-management/api-management-log-to-eventhub-sample
Use policy expressions in Azure API Management policies	https://learn.microsoft.com/en-us/azure/api-management/api-management-policy-expressions
Call external HTTP services from API Management policies	https://learn.microsoft.com/en-us/azure/api-management/api-management-sample-send-request
Import Microsoft Foundry AI endpoints into API Management	https://learn.microsoft.com/en-us/azure/api-management/azure-ai-foundry-api
Import Azure OpenAI model APIs as REST in API Management	https://learn.microsoft.com/en-us/azure/api-management/azure-openai-api-from-specification
Configure GraphQL field resolvers in Azure API Management

Deployment

Topic	URL
Configure autoscale rules for Azure API Management instances	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-autoscale
Deploy Azure API Management across multiple regions	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-deploy-multi-region
Backup and restore Azure API Management for disaster recovery	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-disaster-recovery-backup-restore
Migrate Azure API Management instances between regions	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-migrate
Provision gateway resources for self-hosted API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-provision-self-hosted-gateway
Check regional availability of API Management v2 tiers	https://learn.microsoft.com/en-us/azure/api-management/api-management-region-availability
Deploy Azure API Management to an external virtual network	https://learn.microsoft.com/en-us/azure/api-management/api-management-using-with-vnet
Automate deployment of API Management developer portal content	https://learn.microsoft.com/en-us/azure/api-management/automate-portal-deployments
Automate Azure API Management operations with Azure Automation	https://learn.microsoft.com/en-us/azure/api-management/automation-manage-api-management
Plan for suspension of API Management managed certificates	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/managed-certificates-suspension-august-2025