By default, there are two ways a consumer can specify the Subscription Key
on a call
to API Management:
- Using the
Ocp-Apim-Subscription-Key
HTTP header - Using the
subscription-key
query string value in the URL
These are just the default names for both. While they can be customized, it can be non-obvious how to do this, since it is not exposed directly in the user interface in the Publisher or the Azure Portals.
Both of these options are part of the definition of the ARM resource for the API (yes, APIs, Products, and other API Management entities are essentially nested ARM resources within the API management instance):
There are a few easy ways you can customize this:
Using PowerShell
If you’re comfortable using the PowerShell Azure cmdlets, then it’s possible to change these properties
using the Set-AzureRmApiManagementApi
cmdlet. For example, let’s change the header name
to ApiKey
and the query string value name to api-key
:
$apim = New-AzureRmApiManagementContext -ResourceGroupName $resourceGroup -ServiceName $resourceName
$echoApi = Get-AzureRmApiManagementApi -Context $apim -ApiId 'echo-api'
Set-AzureRmApiManagementApi -Context $apim `
-ApiId $echoApi.ApiId `
-Name $echoApi.Name `
-ServiceUrl $echoApi.ServiceUrl `
-Protocols $echoApi.Protocols `
-SubscriptionKeyHeaderName 'ApiKey' `
-SubscriptionKeyQueryParamName 'api-key'
This is a bit more annoying than it should be, because Set-AzureRmApiManagementApi
has the
ApiId
, Name
, ServiceUrl
, and Protocols
parameters marked as mandatory, so we need to provide
a value even if we’re not trying to change any of them. Simplest way around this is to first query
the current values and pass them back when modifying the API definition.
Using the REST API
Another option is to use any tool that can be used to call REST APIs, if you have the management REST API in API Management enabled.
To do this, first get an access token for the service using the Azure Portal or the publisher portal.
Here, I’ll use Postman to change the properties:
Using the Azure Portal?
At this point, it does not appear to be a way to change these options from the Azure Portal. The new experience for editing APIs is quite nice, and you can check the current values using the following process:
- Select the API you want to modify
- Make sure the Design tab is selected
-
Click on the pencil icon next to the Frontend section to edit the raw API definition
- You will see a YAML definition for the API, including a
securityDefinitions
section where the names of the header and query string value are defined.
While you can modify these settings here, and then save the API definition, the changes appear to be ignored, so it’s not, currently, a viable alternative.