Edit

Share via

API Management policy reference

  • Article

APPLIES TO: All API Management tiers

This section provides brief descriptions and links to reference articles for all API Management policies. The API Management gateways that support each policy are indicated. For detailed policy settings and examples, see the linked reference articles.

More information about policies:

Important

Limit call rate by subscription and Set usage quota by subscription have a dependency on the subscription key. A subscription key isn't required when other policies are applied.

Rate limiting and quotas

Policy Description Classic V2 Consumption Self-hosted
Limit call rate by subscription Prevents API usage spikes by limiting call rate, on a per subscription basis. Yes Yes Yes Yes
Limit call rate by key Prevents API usage spikes by limiting call rate, on a per key basis. Yes Yes No Yes
Set usage quota by subscription Allows you to enforce a renewable or lifetime call volume and/or bandwidth quota, on a per subscription basis. Yes Yes Yes Yes
Set usage quota by key Allows you to enforce a renewable or lifetime call volume and/or bandwidth quota, on a per key basis. Yes No No Yes
Limit concurrency Prevents enclosed policies from executing by more than the specified number of requests at a time. Yes Yes Yes Yes
Limit Azure OpenAI Service token usage Prevents Azure OpenAI API usage spikes by limiting language model tokens per calculated key. Yes Yes No No

Authentication and authorization

Policy Description Classic V2 Consumption Self-hosted
Check HTTP header Enforces existence and/or value of an HTTP header. Yes Yes Yes Yes
Get authorization context Gets the authorization context of a specified connection to a credential provider configured in the API Management instance. Yes Yes Yes No
Restrict caller IPs Filters (allows/denies) calls from specific IP addresses and/or address ranges. Yes Yes Yes Yes
Validate Microsoft Entra token Enforces existence and validity of a Microsoft Entra (formerly called Azure Active Directory) JWT extracted from either a specified HTTP header, query parameter, or token value. Yes Yes Yes Yes
Validate JWT Enforces existence and validity of a JWT extracted from either a specified HTTP header, query parameter, or token value. Yes Yes Yes Yes
Validate client certificate Enforces that a certificate presented by a client to an API Management instance matches specified validation rules and claims. Yes Yes Yes Yes
Authenticate with Basic Authenticates with a backend service using Basic authentication. Yes Yes Yes Yes
Authenticate with client certificate Authenticates with a backend service using client certificates. Yes Yes Yes Yes
Authenticate with managed identity Authenticates with a backend service using a managed identity. Yes Yes Yes Yes

Content validation

Policy Description Classic V2 Consumption Self-hosted
Validate content Validates the size or content of a request or response body against one or more API schemas. The supported schema formats are JSON and XML. Yes Yes Yes Yes
Validate GraphQL request Validates and authorizes a request to a GraphQL API. Yes Yes Yes Yes
Validate OData request Validates a request to an OData API to ensure conformance with the OData specification. Yes Yes Yes Yes
Validate parameters Validates the request header, query, or path parameters against the API schema. Yes Yes Yes Yes
Validate headers Validates the response headers against the API schema. Yes Yes Yes Yes
Validate status code Validates the HTTP status codes in responses against the API schema. Yes Yes Yes Yes

Routing

Policy Description Classic V2 Consumption Self-hosted
Forward request Forwards the request to the backend service. Yes Yes Yes Yes
Set backend service Changes the backend service base URL of an incoming request to a URL or a backend. Referencing a backend resource allows you to manage the backend service base URL and other settings in a single place. Also implement load balancing of traffic across a pool of backend services and circuit breaker rules to protect the backend from too many requests. Yes Yes Yes Yes
Set HTTP proxy Allows you to route forwarded requests via an HTTP proxy. Yes Yes Yes Yes

Caching

Policy Description Classic V2 Consumption Self-hosted
Get from cache Performs cache lookup and return a valid cached response when available. Yes Yes Yes Yes
Store to cache Caches response according to the specified cache control configuration. Yes Yes Yes Yes
Get value from cache Retrieves a cached item by key. Yes Yes Yes Yes
Store value in cache Stores an item in the cache by key. Yes Yes Yes Yes
Remove value from cache Removes an item in the cache by key. Yes Yes Yes Yes
Get cached responses of Azure OpenAI API requests Performs cache lookup using semantic search and returns a valid cached response when available. Yes Yes Yes Yes
Store responses of Azure OpenAI API requests to cache Caches response according to the Azure OpenAI API cache configuration. Yes Yes Yes Yes

Transformation

Policy Description Classic V2 Consumption Self-hosted
Set request method Allows you to change the HTTP method for a request. Yes Yes Yes Yes
Set status code Changes the HTTP status code to the specified value. Yes Yes Yes Yes
Set variable Persists a value in a named context variable for later access. Yes Yes Yes Yes
Set body Sets the message body for a request or response. Yes Yes Yes Yes
Set HTTP header Assigns a value to an existing response and/or request header or adds a new response and/or request header. Yes Yes Yes Yes
Set query string parameter Adds, replaces value of, or deletes request query string parameter. Yes Yes Yes Yes
Rewrite URL Converts a request URL from its public form to the form expected by the web service. Yes Yes Yes Yes
Convert JSON to XML Converts request or response body from JSON to XML. Yes Yes Yes Yes
Convert XML to JSON Converts request or response body from XML to JSON. Yes Yes Yes Yes
Find and replace string in body Finds a request or response substring and replaces it with a different substring. Yes Yes Yes Yes
Mask URLs in content Rewrites (masks) links in the response body so that they point to the equivalent link via the gateway. Yes Yes Yes Yes
Transform XML using an XSLT Applies an XSL transformation to XML in the request or response body. Yes Yes Yes Yes
Return response Aborts pipeline execution and returns the specified response directly to the caller. Yes Yes Yes Yes
Mock response Aborts pipeline execution and returns a mocked response directly to the caller. Yes Yes Yes Yes

Cross-domain

Policy Description Classic V2 Consumption Self-hosted
Allow cross-domain calls Makes the API accessible from Adobe Flash and Microsoft Silverlight browser-based clients. Yes Yes Yes Yes
CORS Adds cross-origin resource sharing (CORS) support to an operation or an API to allow cross-domain calls from browser-based clients. Yes Yes Yes Yes
JSONP Adds JSON with padding (JSONP) support to an operation or an API to allow cross-domain calls from JavaScript browser-based clients. Yes Yes Yes Yes

Integration and external communication

Policy Description Classic V2 Consumption Self-hosted
Send request Sends a request to the specified URL. Yes Yes Yes Yes
Send one way request Sends a request to the specified URL without waiting for a response. Yes Yes Yes Yes
Log to event hub Sends messages in the specified format to an event hub defined by a Logger entity. Yes Yes Yes Yes
Send request to a service (Dapr) Uses Dapr runtime to locate and reliably communicate with a Dapr microservice. To learn more about service invocation in Dapr, see the description in this README file. No No No Yes
Send message to Pub/Sub topic (Dapr) Uses Dapr runtime to publish a message to a Publish/Subscribe topic. To learn more about Publish/Subscribe messaging in Dapr, see the description in this README file. No No No Yes
Trigger output binding (Dapr) Uses Dapr runtime to invoke an external system via output binding. To learn more about bindings in Dapr, see the description in this README file. No No No Yes

Logging

Policy Description Classic V2 Consumption Self-hosted
Trace Adds custom traces into the request tracing output in the test console, Application Insights telemetries, and resource logs. Yes Yes1 Yes Yes
Emit metrics Sends custom metrics to Application Insights at execution. Yes Yes Yes Yes
Emit Azure OpenAI token metrics Sends metrics to Application Insights for consumption of language model tokens through Azure OpenAI service APIs. Yes Yes No No

1 In the V2 gateway, the trace policy currently does not add tracing output in the test console.

GraphQL resolvers

Policy Description Classic V2 Consumption Self-hosted
Azure SQL data source for resolver Configures the Azure SQL request and optional response to resolve data for an object type and field in a GraphQL schema. Yes Yes No No
Cosmos DB data source for resolver Configures the Cosmos DB request and optional response to resolve data for an object type and field in a GraphQL schema. Yes Yes No No
HTTP data source for resolver Configures the HTTP request and optionally the HTTP response to resolve data for an object type and field in a GraphQL schema. Yes Yes Yes No
Publish event to GraphQL subscription Publishes an event to one or more subscriptions specified in a GraphQL API schema. Configure the policy in a GraphQL resolver for a related field in the schema for another operation type such as a mutation. Yes Yes Yes No

Policy control and flow

Policy Description Classic V2 Consumption Self-hosted
Control flow Conditionally applies policy statements based on the results of the evaluation of Boolean expressions. Yes Yes Yes Yes
Include fragment Inserts a policy fragment in the policy definition. Yes Yes Yes Yes
Retry Retries execution of the enclosed policy statements, if and until the condition is met. Execution will repeat at the specified time intervals and up to the specified retry count. Yes Yes Yes Yes
Wait Waits for enclosed Send request, Get value from cache, or Control flow policies to complete before proceeding. Yes Yes Yes Yes

Related content

For more information about working with policies, see: