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

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?

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>