HTTP 401 Access Denied when calling Azure Cognitive Services APIs

 

When calling one of the Cognitive Services APIs you may receive an HTTP 401 Access Denied error with a message “Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.”

 

Here are the most common causes and solutions for this issue.

 

Using the wrong API account key in the Ocp-Apim-Subscription-Key header

When first starting out with Azure or with Cognitive Services it can be confusing to understand which key to use in your application.  It is common to see developers use the Azure subscription key, which is a GUID with a format like 4b2714d2-3d2e-4b96-ad95-677f764e7b39, instead of the API account key.

Make sure you are using one of the 2 API account keys which look like 18de248475134eb49ae4a4e94b93461c.  This key can be found in the Azure Management portal by going to a Cognitive Service and selecting Keys under Resource Management.  There is a walkthrough for creating an account and finding the keys at https://docs.microsoft.com/en-us/azure/cognitive-services/cognitive-services-apis-create-account.

 

You can also call Get-AzureRmCognitiveServicesAccountKey from Powershell to get the correct account key.  I use this script to print out all Cognitive Services accounts and keys in my subscription:

PS C:\Users\kwill> $formatstring = "{0,-29} {1,-19} {2,34} {3,34} {4, 5}"; $formatstring -f "Account", "Type", "Key1", "Key2", "SKU"; Get-AzureRmCognitiveServicesAccount |
ForEach-Object {$account = $_; $keys = Get-AzureRmCognitiveServicesAccountKey -ResourceGroupName $_.ResourceGroupName -Name $account.AccountName; $formatstring -f $account.Ac
countName, $account.AccountType, $keys.Key1, $keys.Key2, $account.sku.Name}
Account Type Key1 Key2 SKU
kwillAcademic Academic 21b2b86e7b78abcde282bb5d602f8867 6f77ba002185abcdeeed04127da5e70d S0
kwillBingSearchS5 Bing.Search c7d85f71945abcdebdff2303c3c4d285 8f0de6ed747446abcdee3db939b401c0 S5
kwillBingSpeech Bing.Speech 98de24847513abcdeae4a4e94b93461d ad2269940791abcdea36b7389167c838 S0
kwillBingSpellCheck Bing.SpellCheck a8007a55a725abcde80ffd96d26664d3 6c118bba971d4abcde7d8d71e12fee6a S1

...

 

 

Using an account key for the wrong API type

Each Cognitive Services API has its own account key, and you can’t use an account key for one API when making a call to another API.  Generally this is a pretty easy concept and not common for developers to run into, but for the Translator API this can be confusing because there is a Translator Text API and a Translator Speech API.  They both use the same API endpoint, but the two keys cannot be used interchangeably. 

You can confirm that you are using the correct API type that matches the API that you are calling by checking the API type and Endpoint in the Azure management portal.  Make sure that the URL you are using for the API call matches the key for the API account.

 

 

Using the incorrect regional endpoint

Most of the Cognitive Services APIs are region specific, which means that during API account creation you select which region you want to create the account in.  These APIs have region specific endpoints such as westus.api.cognitive.microsoft.com or eastus2.api.cognitive.microsoft.com, and an API key for an account created in one region will only work using the endpoint for that specific region.  This means that if you create an API account in West US you will not be able to call the eastus2.api.cognitive.microsoft.com API endpoint.

 

You can verify the region and endpoint in the Azure management portal.

 

This also applies to the web based testing console.  The API documentation will show the different regions available and links to the different regional testing consoles.  Here is the Face API documentation as an example:

 

There are a few additional scenarios where issues with the regional API keys are commonly seen:

• Applications that use Cognitive Service APIs.  If you are using a packaged application that asks you for an API key (for example, a Translator application using the Translator API) the application *should* also ask for the endpoint or region.  However, many applications were built before the Cognitive Services APIs had multiple region specific endpoints so they may not provide an option to configure an endpoint.  In this case the app is usually built using the West US region (westus.api.cognitive.microsoft.com).

• If you use the client library SDKs you will often instantiate the client using code like:

      IFaceServiceClient faceServiceClient = new FaceServiceClient("key");

  This will use the default West US endpoint, which will fail for accounts in other regions. To resolve, pass in the optional endpoint parameter like this:

      IFaceServiceClient faceServiceClient = new FaceServiceClient(key,"https://westeurope.api.cognitive.microsoft.com/face/v1.0");   

• The LUIS.AI portal also has regional endpoints, and creating an app in the LUIS.AI portal must be done in the same region as the LUIS API account that was created in the Azure management portal.  For example, if you create a LUIS API account in West Europe you must use the https://eu.luis.ai portal to create the LUIS application.  In this scenario you may also get the error "Bad Argument, Invalid Subscription Key" from the LUIS.AI portal.

 

 

Using the incorrect version endpoint

Some APIs, such as Bing Search, have multiple versions.  As we release new versions of the APIs we release them as free APIs that can be obtained from https://azure.microsoft.com/en-us/try/cognitive-services/, but these new versions may not yet be available in Azure, and calling them with your Azure API account key will fail with a 401.

As of this blog post, the Bing Search API accounts created via Azure Cognitive Services use the v5.0 version of the API with the endpoint https://api.cognitive.microsoft.com/bing/v5.0.  We have also released a preview version of the v7.0 API with the endpoint https://api.cognitive.microsoft.com/bing/v7.0.  If you call the v7.0 endpoint with an Azure account key it will fail.  You can verify the correct endpoint in the Azure management portal:

 

 

Using the LUIS programmatic key instead of the API account key

There are three different API keys that can be used with LUIS applications:

1. Programmatic Key, which is used to automate the management of LUIS applications created via the LUIS.AI portal.  This is created and accessed via the LUIS.AI portal.
2. API Endpoint Key, which is used by a LUIS application to call into the LUIS API for processing.  This is created and accessed via the Azure Management portal in the Azure Cognitive Services LUIS account blade.
3. External Keys, which are used by a LUIS application to provide additional functionality such as Spell Check.

Further documentation about these 3 keys can be found at https://docs.microsoft.com/en-us/azure/cognitive-services/LUIS/manage-keys.

 

Each of these API keys are specific to their use cases and you will get a 401 if you try to use an API key against the wrong endpoint. 

• You cannot use the Programmatic Key which you get from the LUIS.AI portal when making a LUIS API call to https://westus.api.cognitive.microsoft.com/luis/v1/application such as Analyze Intents. 
• You cannot use your API account key that you get from Azure when making a LUIS Programmatic call to https://westus.api.cognitive.microsoft.com/luis/api/v2.0/apps/ such as Add Application.

 

 

Calling an API immediately after creating an account or regenerating keys

The API keys can take a few minutes to be provisioned and propagated within the various subsystems that make up the Cognitive Services service.  If you try to call an API before the keys have propagated you will get a 401 error.  Wait up to 10 minutes and then try making the API call again.  This is also noted in the Account Keys blade in the Azure Management portal:

 

 

Trial API Keys

The free trial API keys have 30 day expiration dates, and the same restrictions for region and version.  If you are using the trial keys you can go to https://azure.microsoft.com/en-us/try/cognitive-services/my-apis/ to manage your API keys (if you are not already logged in then just click one of the ‘Create’ buttons and you can go through the wizard to login and see your existing API keys), and you will also see the expiration date and endpoint.

 

 

Troubleshooting

If you are troubleshooting a 401 error, the best place to start is the API testing console.  Usually the testing console requires minimal input (often just the API key) so it is ideal to help isolate problems that may be caused by something like custom code or machine specific issues.

 

 

You can get to the testing console by going to one of your Cognitive Services API accounts in the Azure management portal and clicking Quick start and then API reference:

 

You can also get to the testing console by going to the main Cognitive Services documentation page at https://docs.microsoft.com/en-us/azure/cognitive-services/, selecting a service under the “Services/APIs” list on the left, and then going to the Reference –> API Reference section.

Comments

• Anonymous
  June 22, 2017
  Really helpful, save us a lot time!