Secure APIs by using subscriptions
When you publish APIs through API Management, it's easy and common to secure access to those APIs by using subscription keys. Developers who need to consume the published APIs must include a valid subscription key in HTTP requests when they make calls to those APIs. Otherwise, the calls are rejected immediately by the API Management gateway. They aren't forwarded to the back-end services.
To get a subscription key for accessing APIs, a subscription is required. A subscription is essentially a named container for a pair of subscription keys. Developers who need to consume the published APIs can get subscriptions. And they don't need approval from API publishers. API publishers can also create subscriptions directly for API consumers.
Note
API Management also supports other mechanisms for securing access to APIs, including: OAuth2.0, Client certificates, and IP allow listing.
Subscriptions and Keys
A subscription key is a unique auto-generated key that can be passed through in the headers of the client request or as a query string parameter. 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 | This scope 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. |
Applications that call a protected API must include the 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.
Every subscription has two keys, a primary and a secondary. 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 where 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 when they make calls to API endpoints that are protected by a subscription. Keys can be passed in the request header, or as a query string in the URL.
The default header name is Ocp-Apim-Subscription-Key, and the default query string is subscription-key.
To test out your API calls, you can use 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:
Here's how you can pass a key in the request header using curl:
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Here's an example curl command that passes a key in the URL as a query string:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
If the key is not passed in the header, or as a query string in the URL, you'll get a 401 Access Denied response from the API gateway.