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 API Management issues: request tracing, SNAT port exhaustion, custom domain/Key Vault cert errors, and developer portal problems using Diagnose and Solve tools.
Best Practices	L46-L54	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	L55-L73	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	L74-L79	Patterns for placing API Management behind App Gateway/WAF, Azure Front Door, or AKS, including routing, security, and high‑availability reference architectures.
Limits & Quotas	L80-L100	Limits, quotas, and throttling rules for APIs (REST/SOAP/WebSocket), including rate/usage caps, token limits, validation policies, and service/gateway constraints in Azure API Management.
Security	L101-L143	Securing Azure API Management and AI Gateway: authN/Z (Entra ID, B2C, OAuth2, JWT, mTLS, basic), TLS/certs, RBAC, managed identities, self-hosted gateway security, and DDoS/Defender protections.
Configuration	L144-L242	Configuring Azure API Management and AI Gateway: networking/VNet, domains, auth, caching, policies, backends, monitoring, self-hosted gateways, infrastructure-as-code, and LLM/MCP-specific settings.
Integrations & Coding Patterns	L243-L275	Patterns and samples for integrating API Management with AI/LLM backends, logging/monitoring, Event Hubs/Service Bus/Dapr, OAuth/Graph, and importing APIs from OpenAPI, SAP, web apps, and tools.
Deployment	L276-L296	Deploying and scaling API Management: autoscale, multi-region, backup/restore, vNet/external access, self-hosted gateways (AKS/K8s/Docker/Arc), portal automation, APIOps, and MCP versioning.

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
Diagnose SNAT port exhaustion in 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
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
Plan DevOps and CI/CD pipelines for Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/devops-api-development-templates
Migrate Amazon API Gateway workloads to Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/migrate-amazon-api-gateway-to-api-management
Use API Management features to support API monetization	https://learn.microsoft.com/en-us/azure/api-management/monetization-support
Plan and manage Azure API Management costs	https://learn.microsoft.com/en-us/azure/api-management/plan-manage-costs
Upgrade and scale Azure API Management tiers and units	https://learn.microsoft.com/en-us/azure/api-management/upgrade-and-scale
Choose and configure virtual network options for API Management	https://learn.microsoft.com/en-us/azure/api-management/virtual-network-concepts

Architecture & Design Patterns

Topic	URL
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
Configure flexible throttling in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-sample-flexible-throttling
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 limits in API Management	https://learn.microsoft.com/en-us/azure/api-management/quota-policy
Set rate-limit policy thresholds in API Management	https://learn.microsoft.com/en-us/azure/api-management/rate-limit-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 Azure API Management service limits	https://learn.microsoft.com/en-us/azure/api-management/service-limits
Validate request and response content with size limits	https://learn.microsoft.com/en-us/azure/api-management/validate-content-policy
Validate response headers with validate-headers policy in API Management	https://learn.microsoft.com/en-us/azure/api-management/validate-headers-policy
Validate request parameters with validate-parameters policy in API Management	https://learn.microsoft.com/en-us/azure/api-management/validate-parameters-policy
Validate HTTP status codes with validate-status-code policy	https://learn.microsoft.com/en-us/azure/api-management/validate-status-code-policy
Understand WebSocket API limits in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/websocket-api

Security

Topic	URL
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
Configure OAuth 2.0 authorization in API Management test console	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-oauth2
Protect APIs in API Management using OAuth 2.0 with Microsoft Entra ID	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-protect-backend-with-aad
Configure managed identities for Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-use-managed-service-identity
Configure RBAC roles for Azure API Management access	https://learn.microsoft.com/en-us/azure/api-management/api-management-role-based-access-control
Configure Microsoft Entra applications for product-level OAuth access	https://learn.microsoft.com/en-us/azure/api-management/applications
Use authentication-basic policy to secure backend calls in API Management	https://learn.microsoft.com/en-us/azure/api-management/authentication-basic-policy
Configure managed identity authentication in API Management	https://learn.microsoft.com/en-us/azure/api-management/authentication-managed-identity-policy
Migrate API Management identity providers from ADAL to MSAL	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/identity-provider-adal-retirement-sep-2025
Prepare Azure API Management for TLS 1.0/1.1 retirement	https://learn.microsoft.com/en-us/azure/api-management/breaking-changes/tls-versions-retirement-oct-2025
Configure credential providers in API Management	https://learn.microsoft.com/en-us/azure/api-management/credentials-configure-common-providers
Set up basic username/password auth for API Management developer portal	https://learn.microsoft.com/en-us/azure/api-management/developer-portal-basic-authentication
Configure CORS for API Management developer portal test console	https://learn.microsoft.com/en-us/azure/api-management/enable-cors-developer-portal
Use get-authorization-context policy for credential providers	https://learn.microsoft.com/en-us/azure/api-management/get-authorization-context-policy
Secure serverless APIs via API Management and Azure AD B2C	https://learn.microsoft.com/en-us/azure/api-management/howto-protect-backend-frontend-azure-ad-b2c
Apply llm-content-safety policy in API Management	https://learn.microsoft.com/en-us/azure/api-management/llm-content-safety-policy
Protect Azure API Management with DDoS Protection	https://learn.microsoft.com/en-us/azure/api-management/protect-with-ddos-protection
Enable Defender for APIs protection in API Management	https://learn.microsoft.com/en-us/azure/api-management/protect-with-defender-for-apis
Configure secure access to Azure API Management developer portal	https://learn.microsoft.com/en-us/azure/api-management/secure-developer-portal-access
Secure MCP server access with Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/secure-mcp-servers
Apply Azure Policy compliance controls to API Management	https://learn.microsoft.com/en-us/azure/api-management/security-controls-policy
Configure authentication options for self-hosted gateway	https://learn.microsoft.com/en-us/azure/api-management/self-hosted-gateway-authentication-options
Configure access token authentication for self-hosted gateway	https://learn.microsoft.com/en-us/azure/api-management/self-hosted-gateway-default-authentication
Configure Microsoft Entra authentication for self-hosted gateway	https://learn.microsoft.com/en-us/azure/api-management/self-hosted-gateway-enable-azure-ad
Enable workload identity authentication for self-hosted gateway	https://learn.microsoft.com/en-us/azure/api-management/self-hosted-gateway-enable-workload-identity
Secure perimeter-protected backends with API Management and managed identity	https://learn.microsoft.com/en-us/azure/api-management/using-network-security-perimeter
Validate Microsoft Entra JWTs in API Management	https://learn.microsoft.com/en-us/azure/api-management/validate-azure-ad-token-policy
Enforce client certificate validation in API Management	https://learn.microsoft.com/en-us/azure/api-management/validate-client-certificate-policy
Use validate-graphql-request policy in API Management	https://learn.microsoft.com/en-us/azure/api-management/validate-graphql-request-policy
Configure validate-jwt policy in Azure API Management	https://learn.microsoft.com/en-us/azure/api-management/validate-jwt-policy
Use validate-odata-request policy in API Management	https://learn.microsoft.com/en-us/azure/api-management/validate-odata-request-policy