Mastering Azure API Management Policies with 3 Practical Cases

Martín Belda — Tue, 15 Apr 2025 15:40:20 +0000

Azure API Management service (APIM) comes with a rich policy library that enables you to manage, secure, and manipulate requests/responses in a centralized and scalable way. With over 70+ types of policies, however, it's easy to be lost. In this post, I'll walk you through 3 real-world, use-case scenarios that illustrate how to successfully compose these policies together.

Each case contains a full policy block and a short description of every policy used. Let's begin.

✨ Case 1: Securing and Optimizing an AI-Powered API

Scenario:
You're building an API that connects to Azure OpenAI. The API must be secure, enforce token limits, cache responses intelligently, and log usage for cost control.

<policies>
  <inbound>
    <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
      <openid-config url="https://login.microsoftonline.com/YOUR-TENANT/v2.0/.well-known/openid-configuration" />
    </validate-jwt>
    <rate-limit calls="100" renewal-period="60" />
    <azure-openai-token-limit max-tokens="2048" />
    <azure-openai-emit-token-metric name="total_tokens" />
    <azure-openai-semantic-cache-lookup />
    <cache-lookup vary-by-developer="true" />
    <check-header name="x-api-version" failed-check-httpcode="400" failed-check-error-message="Missing API version header">
      <value>v1</value>
    </check-header>
    <set-header name="x-powered-by" exists-action="override">
      <value>AzureAPIM</value>
    </set-header>
  </inbound>
  <backend>
    <forward-request />
  </backend>
  <outbound>
    <cache-store duration="300" />
    <azure-openai-semantic-cache-store />
    <log-to-eventhub logger-id="openai-logger">
      @{ return "Tokens used: " + context.Variables["total_tokens"]; }
    </log-to-eventhub>
  </outbound>
</policies>

Explanation:

validate-jwt: Ensures only authorized users access the API.
rate-limit: Prevents abuse by throttling calls.
azure-openai-token-limit & emit-token-metric: Enforces OpenAI token constraints and usage logging.
semantic-cache-lookup/store & cache-lookup/store: Layered caching improves performance.
check-header: Validates required custom headers.
set-header: Adds branding info.
log-to-eventhub: Sends logs to Event Hub for auditing.

⚡ Case 2: Internal Microservices Gateway with Data Transformations

Scenario:
You’re building a gateway API for internal microservices that include Dapr bindings, Cosmos DB access, and advanced XML/JSON transformations.

<policies>
  <inbound>
    <authentication-managed-identity resource="https://cosmos.azure.com/" />
    <set-backend-service base-url="https://microservice.internal" />
    <validate-content max-size="102400" />
    <json-to-xml apply="always" />
    <invoke-dapr-binding binding-name="sendEmail" operation="create" />
    <cosmosdb-data-source>
      <query>SELECT * FROM c WHERE c.type = 'event'</query>
    </cosmosdb-data-source>
    <limit-concurrency count="10" />
    <set-variable name="env" value="internal" />
  </inbound>
  <backend>
    <send-request mode="new">
      <set-url>https://other-microservice/api</set-url>
    </send-request>
  </backend>
  <outbound>
    <xml-to-json apply="always" />
    <find-and-replace from="error" to="issue" />
    <emit-metric name="microservice_usage" value="1" />
  </outbound>
</policies>

Explanation:

authentication-managed-identity: Secure Cosmos DB access.
json-to-xml / xml-to-json: Flexible data formatting.
invoke-dapr-binding: Triggers Dapr components.
cosmosdb-data-source: Pulls data into pipeline.
limit-concurrency: Prevents overload.
send-request: Connects to another internal API.
find-and-replace: Cleans outbound data.
emit-metric: Custom usage metric.

🌎 Case 3: Public API with Quotas, CORS, GraphQL, and CDNs

Scenario:
You expose a public API that integrates GraphQL, uses JWT auth, handles global requests, and relies on caching/CDN.

<policies>
  <inbound>
    <cors allow-credentials="true">
      <allowed-origins>
        <origin>https://client.app</origin>
      </allowed-origins>
      <allowed-methods>
        <method>GET</method>
        <method>POST</method>
      </allowed-methods>
    </cors>
    <validate-jwt header-name="Authorization">
      <openid-config url="https://login.microsoftonline.com/YOUR-TENANT/v2.0/.well-known/openid-configuration" />
    </validate-jwt>
    <quota-by-key calls="1000" renewal-period="3600" counter-key="@(context.Request.Headers.GetValueOrDefault("x-user-id", "anon"))" />
    <rate-limit-by-key calls="10" renewal-period="60" counter-key="@(context.Request.IpAddress)" />
    <validate-graphql-request />
    <check-header name="x-client-version">
      <value>1.0</value>
    </check-header>
  </inbound>
  <backend>
    <set-backend-service base-url="https://your-api-backend" />
  </backend>
  <outbound>
    <set-header name="Cache-Control" exists-action="override">
      <value>max-age=600</value>
    </set-header>
    <trace source="app-insights" severity="informational" />
    <return-response>
      <set-status code="200" reason="OK" />
    </return-response>
  </outbound>
</policies>

Explanation:

cors: Enables cross-origin requests from trusted clients.
validate-jwt: Authenticates public users.
quota-by-key / rate-limit-by-key: Enforces fair usage.
validate-graphql-request: Ensures valid GraphQL queries.
trace: Adds observability.
return-response: Ends the pipeline cleanly.

🚀 Final Thoughts

Azure API Management policies give you surgical control over your API’s lifecycle—from security and caching to observability and LLM safety. Use them thoughtfully in layered designs.

If you'd like to go deeper on any policy—or want a complete blueprint for your architecture—just reach out. Let’s build better APIs, one policy at a time.

Follow me for more Azure, API, and cloud-native insights. 🚀

DEV Community: Martín Belda

Mastering Azure API Management Policies with 3 Practical Cases

✨ Case 1: Securing and Optimizing an AI-Powered API

⚡ Case 2: Internal Microservices Gateway with Data Transformations

🌎 Case 3: Public API with Quotas, CORS, GraphQL, and CDNs

🚀 Final Thoughts