Azure API Management | Subscription Contract Names

Problem Space

Subscriptions are a nice and easy method of securing your APIs in APIM, however as I bumped into a small detail around their use the other day, I thought it wise to note it down.

When a Subscription Key is required on an API, as an invoker I will need to provide either a Header or a Parameter to my request which will contain the Subscription Key.

By default:

• The Header is as follows:
  • Ocp-Apim-Subscription-Key: SubscriptionKey
• The Query Parameter is as follows:
  • ?subscription-key=SubscriptionKey

This being said, Azure does also allow you to override these Header and Query Parameter names.

Azure Portal

To view or change these Subscription Contract Names in the Azure Portal, navigate through to your APIM instance - APIs - Select the API you wish to view/change - Select Settings.

As can be seen by the image below, the header and query parameter name is shown and editable under the Subscription Header in the Portal.

IaC | Bicep

When defining your API Management Service APIs in Bicep, there is a property called subscriptionKeyParameterNames which defines the contract names for your Subscription Header and Query Parameter

The Bicep Template will look similar to the following:

resource symbolicname 'Microsoft.ApiManagement/service/apis@2021-08-01' = {
	name: 'string'
	parent: resourceSymbolicName
	properties: {
		...
		subscriptionRequired = true
		subscriptionKeyParameterNames: {
			header: 'mySubscriptionHeaderName'
			query: 'myQueryParameterSubscriptionName'
		}
		...
	}
}