There is no single, "correct" way to pass in authentication information including APIKeys. This is true for any HTTP API, whether managed in Apigee Edge or not.
As you know, your policies in Apigee Edge can access any part of the inbound message: query parameters, headers, payload, url path elements, and methods.
You can choose any one of those options.
You mentioned "key leakage" as a problem. for sure, eliminating the possibility to transmit keys in the query string is a good idea. Also, using TLS to secure the transport layer may also be recommended.
As for whether using the Authorization header WITH an APIKEY prefix is necessary. The spec recommends it, so obviously it's not *wrong*, but it does seem like an extra bit of formality and strictness that isn't contributing any value to either the caller or the receiver. And maybe it is contributing some "cost" in terms of complexity. In particular on the caller side, the developer would need to add that prefix to every call. (one extra string concatenation). On the server side, you would need the converse - a string split - and then you'd need to validate that the prefix was the prefix you were expecting: Apikey and none other. What is the point of all this extra framing? To me, the simplest thing that works is the best, and this APIKEY prefix would represent extra framing.
The prefix seems like it would be a really good idea if your API endpoint needed to handle multiple distinct kinds of authentication: Key, Token, Signature, and so on. And all of them were alternatives, that could be requested via different values in the same request header. There, the prefix disambiguates the remaining payload of the header. However, if your API doesn't support multiple auth values, then it just seems like an unnecessary extra bit of protocol.
You may say: what if, in the future, I would like to introduce a new authentication mechanism, distinct from APIKey? Wouldn't it be smart to use the prefix now to allow this future possibility? Here, I think YAGNI applies. Even if you implement an extension like this in the future, you can introduce prefixes THEN, and any header with no prefix, just treat as an APIKey by default. So there's still no problem. And if the purist in you insists on always including a prefix if any of the Authentication headers require a prefix, why, you could simply increment the API revision to handle that case.
So in summary, "meh" on the APIKEY prefix.
The counter-argument is obviously "OAuth v2 uses the Bearer prefix". Quite true, but all of my reasoning applies there as well. It's still unnecessary. But there are lots of tools that know how to build or parse "standard" OAuthV2 headers, so that prefix will likely remain. (In Apigee Edge, the policy that verifies an OAuthV2 token by default expects to find and strip out the Bearer prefix, but you can configure it to expect a different prefix, or no prefix).
Regarding rfc7235 and the recommendation to use the WWW-Authenticate response header, surely that is a good idea. That is a good practice which has been in use for some time. However, if you document your API correctly, it is not strictly necessary. You can simply state in the documentation how the caller needs to authenticate (pass a key, sign the request, etc), and a 401 Unauthorized need not be transmitted with additional information in the case of an authentication failure.
In other words, It might be developer-friendly to distinguish between a 401 because of a missing key, and a 401 because of an expired key, and a 401 because of an present-but-invalid key, but it is not strictly necessary.
LinkedIn
Twitter
