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?

• Andy: The projects under my guidance use Authorization: Bearer <token> header and there was never a single issue with that. The tokens are JWTs.
• RomanG: @DavidPacker As I understand, Bearer scheme is used exclusively with oAuth2. Applying it separately from oAuth sounds as misusing it. Why is it correct to use this scheme if there is no oAuth? By the way, I had troubles with choosing a type of authorization for my API. The API will be available only for one trusted service, so I investigated the client credentials flow of oAuth2 and haven't found any benefit in comparison with ApiKey in my case.
• RomanG: @DavidPacker Then I understood, that the ApiKey authorization could be considered as a valid oAuth implementation if ApiKey was renamed and interpreted as an Access Token granted to the client without an expiration time. That's a kind of philosophical aspect, I decided not to bring complex definitions if my case can be described in simple terms and decided to just call it "ApiKey". If your protocol implements oAuth standart, I can agree on using Bearer, but it doesn't, I guess this scheme can't be applied.
• Andy: You're limiting yourself too much. The API consumer could not care less whether you have implemented OAuth or not. What they care about is token safety, that token issuing works and that they can get properly authenticated. They recommend to use Bearer right in the JWT documentation. JWT fits the Bearer schema perfectly well and I could not recommend JWTs more. They are perfect for REST applications because you can authenticate a user even without hitting the database - unless you need token revocation feature.
• K. Alan Bates: (drive by) ...please take care to know that api keys are shared secrets typically shared between a configured relying party and an authenticator, not to communicate identity or authorization. Stated another way, they are only intended to initiate a security handshake, not represent an authentication result. The api key communicates your authority to identify yourself against the system's trusted authenticator. Using the key as an token to control secure resource access is bad juju

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}

• Dani: The using of X- is deprecated as of 2012: stackoverflow.com/a/3561399/923720
• Laiv: ops! I didn't know. Edited and fixed.
• user949300: Before this question I thought most everybody put the API key in the URL, but used HTTPS to hide it. Good to see some alternatives. For example, Contentful allows Authorization or query pamameter: contentful.com/developers/docs/references/content-delivery-api/…
• K. Alan Bates: @user949300 ...using an encrypted shared secret (e.g. api key in uri over ssl) is obviously more secure than nothing at all, but is easily spoofable if it is intercepted and provides no granularity over identities. I have never used api_keys for anything other than machine to machine communication where I am matching the shared secret between trusting parties and the whitelisted machine identities authorized to act with that shared secret. After the machine to machine conn is made, the human operator authenticates using other means.
• Andrew Martinez: There is a difference in how CORS operates w/ custom headers vs the Authorization header. In the response to a preflight CORS OPTION request, the Authorization header is not included in the wildcard (*) response and must be explicitly sent.