Create subscriptions in Azure API Management


When you publish an API with API Management, you define who can access the API through the gateway.

For your meteorological app, you want to ensure that only customers who have subscribed to your service can access the API and use your forecast data. You accomplish this access control by issuing subscription keys.


Subscriptions in this context are not related to Azure subscriptions used for managing your Azure account.

Here, you'll learn how to use subscription keys to secure your APIs.

Subscriptions and keys

You can choose to make your APIs and the information they contain freely available. But usually, you want to restrict access to users who have paid or organizations with which you have a working relationship. One way to control access to your APIs is by using subscriptions. Subscriptions are used to segment user access to an API.

Subscription keys form the authorization to enable access to these subscriptions. Whenever a client makes a request to a protected API, a valid subscription key must be included in the HTTP request, otherwise the call will be rejected.

A subscription key is a unique autogenerated key that can be passed as part of an API call. The key is directly related to a subscription, which can be scoped to different areas. Subscriptions give you granular control over permissions and policies.

The three main subscription scopes are:

Scope Details
All APIs Applies to every API accessible from the gateway.
Single API Applies to a single imported API and all of its endpoints.
Product A product is a collection of one or more APIs that you configure in API Management. You can assign APIs to more than one product. Products can have different access rules, usage quotas, and terms of use. So, if you want your partners and suppliers to have different access rights to your WeatherData API, assign the API to a product, and then use the Azure portal to associate APIs with a product.

Applications that call a protected API must include a subscription key in every request.

You can regenerate these subscription keys at any time; for example, if you suspect that a key has been shared with unauthorized users, you can create a new one.

Subscription keys.

Every subscription has two keys - a primary key and a secondary key. Having two keys makes it easier when you do need to regenerate a key. For example, if you want to change the primary key and avoid downtime, use the secondary key in your apps.

For products in which subscriptions are enabled, clients must supply a key when making calls to APIs in that product. Developers can obtain a key by submitting a subscription request. If you approve the request, you must send them the subscription key securely, for example, in an encrypted message. This step is a core part of the API Management workflow.

Call an API with the subscription key

Applications must include a valid key in all HTTP requests that make calls to API endpoints that are protected by a subscription. Keys can be passed in the request header or as a query string parameter in the URL.

The default subscription key header name is Ocp-Apim-Subscription-Key, and the default query string name is subscription-key.

To test out your API calls, you can use a test console in the Azure portal, or the developer portal, or command-line tools, such as curl. Here's an example of a GET request using the developer portal, which shows the subscription key header:

Screenshot that shows how to call your API from developer portal.

Here's an example of how you would pass a key in a request header using curl:

curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>

Here's an example of how you would use a curl command to pass a key as a query string in a URL:

curl https://<apim gateway><key string>

If a required key isn't passed in the header, or as a query string in the URL, you'll get a 401 Access Denied response from the API gateway.