Where to place an API key: a custom HTTP header VS the Authorization header with a custom scheme

Question

I'm designing a REST API using authorization/authentication via an API Key.

I tried to figure out what is the best place for it and found out that many people suggest using a custom HTTP header such as ProjectName-Api-Key, eg:

ProjectName-Api-Key: abcde

but also it's possible and ideologically correct to use the Authorization header with a custom scheme, eg:

Authorization: ApiKey abcde

On the other hand, I found a consideration that a custom Authorization scheme can be unexpected and unsupported by some clients and leads to custom code anyway, so it's better to use a custom header since clients don't have any expectations about it.

Which way would you prefer to send an API Key?

Answer 1

Be consistent

Some may say this is unnecessary (and not too long ago I would have agreed) but these days, with so many auth protocols, if we use the Authorization header to pass an API key, it is worth informing the type too because API keys are not self-descriptive per se ¹.

Why do I think it is worth it? Because nowadays supporting different authentication or/and authorization protocols has become a must-have. If we plan to use the Authorization header for all these protocols, we have to make our auth service consistent. The way to communicate what kind of token we send and what authorization protocol should be applied should go in the header too.

Authorization: Basic XXXX
Authorization: Digest XXXX
Authorization: Bearer XXXX
Authorization: ApiKey-v1 XXXX
Authorization: ApiKey-v2 XXXX

I used to don't care about this, but after working with mobile clients or sensors, in which updates were not guaranteed, I started to. I started to be more consistent in the way I implement security so that I can keep backwards compatibility. With the token's type informed I can invalidate requests from a specific set of clients (the outdated ones), add new schemes and differentiate old clients from new ones and change auth validations for one or another scheme without causing breaking changes. I also can apply specific rules in the API Gateways based on the authorization scheme. For example, I can redirect old schemes to specific versions of my web APIs which are deployed apart from the main ones.

Concerns

The problems I faced implementing my own schemes have been similar to the one commented.

On the other hand, I found a consideration that a custom Authorization scheme can be unexpected and unsupported by some clients and leads to custom code anyway

Say clients, say libraries, frameworks, reverse proxies. A custom header can be rejected or ignored. In the worse of the cases, it can also collide.

Collisions can be problematic, but all other issues are likely to be solved by tackling configurations.

Advantages

One important advantage is cache. Shared caches won't cache the header (and that's good of course) unless you say otherwise.

So Authorization or custom header?

In my experience, both take me almost the same work and time to implement, with a slight difference. I had more room for design when I implemented custom headers. However, more room for design also meant more chances to overcomplicate things or reinvent the wheel.

Technically, there could be very little or no difference between the two, but I have found the consistency to be a good feature. It provides me with clearness and understanding. In my case, adding new schemes was reduced to adding 2 new abstractions (implemented by the same concrete class): TokenHandler and TokenValidator. The Handler only checks whether the request header Authorization informs the supported scheme. The Validator is anything I need to validate the token. Altogether working from a single request filter instead of a chain of filters or a big ball of mud.

---

^{1: I find this answer to be very clear regarding API Keys}