Change APIM Subscription key header name that's already in use - azure

Question

We are currently using the default Ocp-Apim-Subscription-Key header name for Azure APIM subscriptions, and it is used in production by a fair amount of people. We would like to change that without breaking any existing integration, by for example adding support for a second ApiKey header that fulfils the same role, until we can phase out the default APIM one.
Azure only offers the option to change the existing one - which would be a breaking change in our case. How can we deprecate this header safely in favor of a more readable one?

Answer 1

That is not going to be trivial, unfortunately. But there is a way. If you change API's subscription key header name any request coming in with old header will produce 401 response. You could intercept that in API's on-error section and check if old header name is present or not, and if it does - reissue the request. Something along these lines:
<on-error>
<base />
<choose>
<when condition="#(context.Response.StatusCode == 401 && context.Request.Headers.ContainsKey("OCP-APIM-Subscription-Key"))">
<send-request mode="copy" response-variable-name="response">
<set-url>#{
var urlParts = context.Request.OriginalUrl.ToString().Split('/');
urlParts[2] = "127.0.0.1"; //Overriding host to keep request local, but Host header also need to be reset to make SSL work
return string.Join("/", urlParts);
}</set-url>
<set-header name="Host">
<value>#(context.Request.OriginalUrl.Host)</value>
</set-header>
<set-header name="ApiKey">
<value>#(context.Request.Headers.GetValueOrDefault("OCP-APIM-Subscription-Key"))</value>
</set-header>
</send-request>
<return-response response-variable-name="response" />
</when>
</choose>
</on-error>