API Management policies
What it is
API Management policies are runtime rules that the Azure API Management gateway applies to API requests and responses. They can validate a credential, limit request rate, transform a message, route a call, cache a response, or decide how to handle an error—all without changing the backend application’s source code.
Why it exists
An organization may expose many APIs to many clients. Putting the same rate limit, header check, or response-format change in every backend service creates inconsistent and hard-to-maintain code. A gateway policy applies a shared boundary rule before or after the backend call.
Key ideas
- Policies run in the API gateway, between the client and backend. They can act on the inbound request, backend call, outbound response, or error path.
- Policies can be set at broad or narrow scopes: all APIs, a workspace, a product, one API, or one operation. A broad policy has a broad impact.
- A narrower policy does not automatically include its parent policy. The
<base />element controls inheritance and evaluation order in each policy section. Omitting it can accidentally skip a shared authentication, logging, or rate-limit rule. - Common uses include authentication checks, rate limiting, request/response transformation, caching, IP filtering, and routing.
- API Management policies are not Azure Policy. API Management policies govern live API traffic; Azure Policy evaluates and enforces governance rules for Azure resource configuration.
Northwind example
Northwind exposes an order-status API to a delivery partner. Its API gateway checks the partner’s token, limits calls to a safe rate, and adds a required backend header before forwarding valid requests. The backend still checks whether the partner may see the requested order. If Northwind’s gateway policy is too broad or transforms the wrong field, it can break every partner call—so policies are versioned, reviewed, and tested.
Common confusion
- A policy can reject a request before it reaches the backend, but it does not replace backend authorization for business data.
- A rate limit manages traffic pressure; it does not make an API immune to abuse or capacity failures.
- A response transformation can help compatibility, but can also hide errors or change the contract clients rely on.
Related
api-management · azure-policy · northwind-traders-case-study
Sources and re-audit
- Microsoft Learn — Policies in Azure API Management, checked 2026-09-17.