Azure API ManagementAuthorCloudBrum editorial teamLast reviewed24 Oct 2026Reading time~12 minLevelBeginner to advanced

• One address, many back endsAzure Functions, App Service, Logic Apps, containers, virtual machines and even on-premises services can sit behind one domain and one set of rules.
• Policies you can readBehaviour is written in XML that runs at four steps: inbound, backend, outbound and on-error. A rate limit or a token check is usually a line or two.
• Products and subscriptionsBundle APIs into a product, then hand each customer a subscription with its own key and its own limits.
• A developer portalA ready-made site where developers read the API reference and try calls. They can request a key there too. You can restyle it or host your own copy.
• Runs where your APIs runThe self-hosted gateway is a container. Run it in a datacenter, in another cloud or on Kubernetes, and manage it from one Azure instance.
• AI gateway policiesLimit tokens per caller, cache similar prompts, balance across several model deployments and govern MCP servers in front of Azure OpenAI and other model back ends.
• Checks before the back endValidate JWTs, ask for client certificates, filter by IP address or check the shape of a request before anything reaches your code.
• Revisions and versionsTry a change as a revision without touching live traffic, and publish breaking changes as a new version beside the old one.

API and operation

An API is a set of operations, each one a method and path such as GET /orders/{id}. You add them by hand or import an OpenAPI file.

Gateway

The part that receives calls and runs your policies before forwarding to the back end. Azure manages it, or you can self-host it as a container.

Management plane

The portal, ARM and REST API where you configure everything. It is separate from the gateway that handles calls.

Developer portal

The website for people who build against your APIs. It is generated from your API definitions.

Product

A bundle of APIs offered to developers, with its own terms: a rate limit, a quota, and whether approval is needed.

Subscription

A pair of keys that identifies a caller for a product, API or the whole service. Sent in the Ocp-Apim-Subscription-Key header.

Policy

An XML statement that changes what happens to a call. Policies run in order and can be set for the whole service, a product, an API or one operation.

Policy fragment

A reusable block of policy XML that many APIs can include, so a rule like token validation is written once.

Named value

A stored setting or secret used in policies. It can point to a secret in Azure Key Vault instead of holding it.

Backend

A saved definition of where requests go, with its own credentials, circuit breaker and, for pools, load balancing.

Revision

A non-breaking change you can test next to the live one, then make current.

Version

A separate public edition of an API for breaking changes. Callers pick it by path, header or query string.

Workspace

A slice of one instance that a team manages on its own, with APIs, products and policies that belong only to it.

Self-hosted gateway

A Docker container that runs the gateway in your own network and reports back to the Azure instance.

Create an instance and publish your first API in the Azure portal

1. Choose the tier before anything elsePick Developer to learn the full feature set (not for production), Consumption for a quick, low-cost trial that lacks some features, or a v2 tier for a real service. Changing later is possible but not always painless.
2. Create the instanceSearch for API Management services, press Create, give it a globally unique name, a Region, your organisation name and an admin e-mail. Consumption and v2 instances usually appear within minutes. Classic tiers can take half an hour or more.
3. Import an APIUnder APIs choose OpenAPI and paste the definition’s address, or start from an Azure Function, App Service or Logic App. Check the back-end URL it filled in.
4. Test in the portalOpen the Test tab for an operation and send a call. If you get a response, the gateway can reach the back end.
5. Package it as a productCreate a product, add the API, keep Requires subscription on, and publish it. Then create a subscription for a test user and copy a key.
6. Call it with the keySend the request to the gateway URL with the Ocp-Apim-Subscription-Key header. A 401 means the key or the product link is wrong.
7. Add your first policiesIn the policy editor of the API add a JWT check, a rate limit and a CORS rule. Keep the line in each section so rules set at wider scopes still apply.
8. Turn on loggingConnect Application Insights and decide what to sample. Full request and response logging is rarely worth the cost.
9. Go public properlyAdd a custom domain with a certificate, publish the developer portal, and put the instance behind your network rules before real traffic arrives.

• Pick the tier for the load, then watch the capacity metric. Add units before it sits high, and scale back when it doesn’t.
• Cache with cache-lookup and cache-store for responses that rarely change. On Consumption you’ll need an external cache.
• Place the instance in the same Region as the busiest back ends, and use a gateway in each Region when callers are spread out.
• Keep policy expressions short. A send-request to another service inside a policy adds its latency to every call.
• Don’t buffer large bodies unless a policy needs them. Streaming is cheaper than copying.
• Set sensible timeouts and use retry only for calls that are safe to repeat.
• Use backend pools and circuit breakers so a failing back end is skipped quickly.
• Sample telemetry. Logging every call to Application Insights slows nothing much, but it costs a lot.

FinOps is the habit of managing cloud spend together with engineering. These are the FinOps checks that matter most for Azure API Management.

• Choose the tier honestly. Developer for non-production, Consumption for low or spiky traffic, a v2 tier for most production services, Premium only for what needs it.
• Don’t copy production’s tier into test and development; that’s how a spare Premium unit ends up costing thousands a year.
• Watch the capacity metric and use autoscale where your tier supports it, so you aren’t paying for idle units.
• On the classic and v2 tiers, billing runs by the hour while the instance exists. Delete spare instances and rebuild them from code when needed.
• Share one instance between teams with workspaces. Several half-empty instances cost more than one busy one.
• Cache responses that don’t change, and keep expensive back-end calls off the hot path.
• Log to Log Analytics with care. Ingestion charges can pass the gateway’s own cost, so sample and set retention.
• Count the extras too: a Redis cache, Key Vault operations, Defender for APIs, Front Door, and data transfer out.
• For model back ends, set token limits per caller, or one team’s experiment becomes everyone’s invoice.
• Tag instances by owner and product, and set a budget alert on the resource group.

• Don’t treat subscription keys as authentication. Validate JWTs from Entra ID (or another provider) with validate-jwt.
• Require client certificates for partner calls that need them.
• Make the back end accept calls only from the gateway: private endpoint, IP restriction, or a managed identity check.
• Keep secrets in Key Vault named values and give the instance a managed identity.
• Restrict CORS origins, and set ip-filter for known callers.
• Use a virtual network and, where your tier allows, a private endpoint, so the gateway isn’t open to the internet unless it has to be.
• Turn on Defender for APIs to spot unusual use and unprotected endpoints.
• Validate request content and size with validate-content before it reaches the back end.
• Protect the developer portal: sign-in, approval for products and a review of what it shows.
• Send diagnostics to a Log Analytics workspace, use Azure Policy for guardrails, and rotate keys.

Use the Activity log to see who changed an instance, Azure Policy to enforce settings and Microsoft Defender for Cloud for recommendations. Microsoft publishes compliance reports in the Service Trust Portal. As always, responsibility is shared: Microsoft runs the platform, and you own the policies, keys, data and access.

• Right-size the tier and units, and delete instances that no longer serve traffic.
• Cache, so repeated calls never reach the back end.
• Reject abuse early with rate limits and IP filters so it doesn’t use compute downstream.
• Choose Regions close to users and, where rules allow, ones with a lower-carbon grid.
• Log what you will actually read, and keep retention short.
• Share an instance through workspaces rather than giving every team its own.
• The Emissions Impact Dashboard and the Azure carbon optimization tools estimate emissions. Check what they cover for API Management.

Purchase options

What you actually pay for

• Unit-hours for each gateway unit in Developer, Basic, Standard, Premium and the v2 tiers
• Calls above the free allowance on Consumption
• Extra units and extra regions on Premium
• Outbound data transfer
• Related services: Application Insights, Log Analytics, an external Redis cache, Key Vault, Front Door, Private Link and Defender for APIs

Create a Developer-tier instance, import an API from its OpenAPI file, wrap it in a product and attach a policy that checks a JWT, limits each subscription and sets CORS. The Azure CLI and Terraform tabs build it, the XML tab shows the policy on its own, and the C# tab is a caller that sends the key and token and backs off when it is limited. Replace the placeholder names, addresses and tenant details with your own.

# Developer has every feature but no service-level agreement, so it is for learning and testing. It can take 30 to 40 minutes to create.
# For production pick a v2 tier or another tier from the pricing page
RG=rg-orders-api
LOCATION=centralindia
APIM=apim-orders-$RANDOM            # the name becomes https://<name>.azure-api.net, so it must be unique

az group create --name $RG --location $LOCATION

az apim create --name $APIM --resource-group $RG --location $LOCATION \
  --publisher-name "Example Ltd" --publisher-email api@example.com \
  --sku-name Developer

# Import the API from its OpenAPI definition and point it at the back end
az apim api import --resource-group $RG --service-name $APIM \
  --api-id orders --path orders --display-name "Orders API" \
  --specification-format OpenApi --specification-url https://orders.example.com/openapi.json \
  --service-url https://orders.example.com

# A product that needs a subscription key and no manual approval, with the API added to it
az apim product create --resource-group $RG --service-name $APIM \
  --product-id starter --product-name "Starter" --description "Low-volume access for new partners" \
  --subscription-required true --approval-required false --state published

az apim product api add --resource-group $RG --service-name $APIM --product-id starter --api-id orders

# A subscription for a test caller (the CLI has no command for this, so use the management REST API)
SUB_ID=$(az account show --query id --output tsv)
BASE="https://management.azure.com/subscriptions/$SUB_ID/resourceGroups/$RG/providers/Microsoft.ApiManagement/service/$APIM"
az rest --method put --url "$BASE/subscriptions/test-caller?api-version=2022-08-01" \
  --body "{\"properties\":{\"scope\":\"/products/starter\",\"displayName\":\"Test caller\"}}"

# Read the key and make a call
KEY=$(az rest --method post --url "$BASE/subscriptions/test-caller/listSecrets?api-version=2022-08-01" --query primaryKey --output tsv)
curl -i -H "Ocp-Apim-Subscription-Key: $KEY" https://$APIM.azure-api.net/orders/orders

# Developer_1 is for learning and testing (no service-level agreement, and slow to create); pick a v2 or classic tier for production
resource "azurerm_resource_group" "api" {
  name     = "rg-orders-api"
  location = "centralindia"
}

resource "azurerm_api_management" "orders" {
  name                = "apim-orders-example"   # must be globally unique
  location            = azurerm_resource_group.api.location
  resource_group_name = azurerm_resource_group.api.name
  publisher_name      = "Example Ltd"
  publisher_email     = "api@example.com"
  sku_name            = "Developer_1"

  identity {
    type = "SystemAssigned"
  }

  tags = {
    Env   = "dev"
    Owner = "platform-team"
  }
}

resource "azurerm_api_management_api" "orders" {
  name                  = "orders"
  resource_group_name   = azurerm_resource_group.api.name
  api_management_name   = azurerm_api_management.orders.name
  revision              = "1"
  display_name          = "Orders API"
  path                  = "orders"
  protocols             = ["https"]
  service_url           = "https://orders.example.com"
  subscription_required = true

  import {
    content_format = "openapi-link"
    content_value  = "https://orders.example.com/openapi.json"
  }
}

resource "azurerm_api_management_product" "starter" {
  product_id            = "starter"
  api_management_name   = azurerm_api_management.orders.name
  resource_group_name   = azurerm_resource_group.api.name
  display_name          = "Starter"
  subscription_required = true
  approval_required     = false
  published             = true
}

resource "azurerm_api_management_product_api" "starter_orders" {
  api_name            = azurerm_api_management_api.orders.name
  product_id          = azurerm_api_management_product.starter.product_id
  api_management_name = azurerm_api_management.orders.name
  resource_group_name = azurerm_resource_group.api.name
}

# The policy lives in its own file so it can be reviewed and tested like any other code
resource "azurerm_api_management_api_policy" "orders" {
  api_name            = azurerm_api_management_api.orders.name
  api_management_name = azurerm_api_management.orders.name
  resource_group_name = azurerm_resource_group.api.name
  xml_content         = file("${path.module}/orders-policy.xml")
}

output "gateway_url" {
  value = azurerm_api_management.orders.gateway_url
}

<!-- orders-policy.xml: applies to every operation of the Orders API -->
<policies>
    <inbound>
        <base />
        <!-- Browsers may call this API only from our own site -->
        <cors allow-credentials="false">
            <allowed-origins>
                <origin>https://app.example.com</origin>
            </allowed-origins>
            <allowed-methods>
                <method>GET</method>
                <method>POST</method>
            </allowed-methods>
            <allowed-headers>
                <header>authorization</header>
                <header>content-type</header>
                <header>ocp-apim-subscription-key</header>
            </allowed-headers>
        </cors>
        <!-- Only callers with a valid token from our Entra ID tenant -->
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
            <openid-config url="https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0/.well-known/openid-configuration" />
            <audiences>
                <audience>api://orders-api</audience>
            </audiences>
        </validate-jwt>
        <!-- 100 calls a minute for each subscription; the header tells the caller how many are left -->
        <rate-limit-by-key calls="100" renewal-period="60" counter-key="@(context.Subscription.Id)" remaining-calls-header-name="X-Calls-Remaining" />
        <set-header name="X-Request-Id" exists-action="skip">
            <value>@(context.RequestId.ToString())</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
        <!-- Don't tell callers which server software answered -->
        <set-header name="X-Powered-By" exists-action="delete" />
        <set-header name="Server" exists-action="delete" />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

// Program.cs: a caller that sends the subscription key and a token, and backs off politely when the gateway says 429
using System.Net;
using System.Net.Http.Headers;

var baseAddress = new Uri("https://apim-orders-example.azure-api.net/");
var subscriptionKey = Environment.GetEnvironmentVariable("APIM_KEY")!;
var token = Environment.GetEnvironmentVariable("ACCESS_TOKEN")!;   // from Entra ID, for example with Azure.Identity

using var client = new HttpClient { BaseAddress = baseAddress, Timeout = TimeSpan.FromSeconds(30) };
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

for (var attempt = 1; attempt <= 4; attempt++)
{
    using var response = await client.GetAsync("orders/orders?limit=20");

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine(await response.Content.ReadAsStringAsync());
        break;
    }

    if (response.StatusCode == HttpStatusCode.TooManyRequests && attempt < 4)
    {
        // Honour Retry-After when the policy sends it, otherwise wait a little longer each time
        var wait = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(2 * attempt);
        Console.WriteLine($"Limited. Waiting {wait.TotalSeconds:0} s before attempt {attempt + 1}.");
        await Task.Delay(wait);
        continue;
    }

    Console.WriteLine($"Failed with {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");
    break;
}

Short walkthrough videos for this service are being prepared. They will appear here and load only when you press play. Until then, follow CloudBrum on YouTube for new videos.

Not sure a full gateway is the right size? Azure Functions can serve HTTP on its own, Azure Front Door and Application Gateway handle web traffic and WAF, and Azure Container Apps can expose an app directly.