Rotate subscription keys in Cognitive Services

Each Cognitive Services resource has two API keys to enable secret rotation. This is a security precaution that lets you regularly change the keys that can access your service, protecting the privacy of your resource if a key gets leaked.

How to rotate keys

Keys can be rotated using the following procedure:

  1. If you're using both keys in production, change your code so that only one key is in use. In this guide, assume it's key 1.

    This is a necessary step because once a key is regenerated, the older version of that key will stop working immediately. This would cause clients using the older key to get 401 access denied errors.

  2. Once you have only key 1 in use, you can regenerate the key 2. Go to your resource's page on the Azure portal, select the Keys and Endpoint tab, and select the Regenerate Key 2 button at the top of the page.

  3. Next, update your code to use the newly generated key 2.

    It will help to have logs or availability to check that users of the key have successfully swapped from using key 1 to key 2 before you proceed.

  4. Now you can regenerate the key 1 using the same process.

  5. Finally, update your code to use the new key 1.

See also