Return to Answer

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, worth informing the type too because API keys are not self-descriptive per se ¹.

Why do I think it worth it? Because nowadays supporting different authentication or/and authorization protocols have 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, 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, 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 informed. 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 has 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.

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?

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

Technically there could be very little or no difference among the two, but I have found the consistency to be a property of any solution I value for what it provides me, clearness and understanding. In my case, adding new schemes was reduced to add 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 from a chain of filters or a big ball of mud.

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

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}

If you use Authorization, be consistent

Some will argue that the following is unnecessary (and not too long ago I would have agreed with them) but, these days, if we use the Authorization header we should inform the type of the token, because  API keys are not self-descriptive per se ¹.

Why do I think it's necessary and why I do think it's important? Because nowadays supporting different authentication/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 app client apps whose updates were not guaranteed (mobiles and sensors mostly), I started to. I started to be more cautious in the way I implement security so that I can expand it without messing with clients and without too much pain on the server side.

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.

To my experience, implementing my own Authorization scheme has taken me the very same amount of work (or more) than implementing custom authorization headers, with the slight difference of having more freedom of design and more control over the cache when I have used custom headers. The reason is rather stupid, most of the time I have the Cache-control set to no-cache or no-store, allowing me to make the calls to the server more deterministic (this is important when it comes to tracking and testing) regardless the topology of the network.

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, worth informing the type too because API keys are not self-descriptive per se ¹.

Why do I think it worth it? Because nowadays supporting different authentication or/and authorization protocols have 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, 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, 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 informed. For example, I can redirect old schemes to specific versions of my web APIs which are deployed apart from the main ones.

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.

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

Technically there could be very little or no difference among the two, but I have found the consistency to be a property of any solution I value for what it provides me, clearness and understanding. In my case, adding new schemes was reduced to add 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 from a chain of filters or a big ball of mud.

API keys don't belong to any specific authentication or authorization protocol¹. We could use Authorization header but, as you commented, it would take us to implement our own scheme and protocol. Usually reinventing the wheel in security is a bad idea, so it's good to leave Authorization header for well-known authorization standards.².

When I have implemented API Keys authorizations, I wanted to state clearly that the authentication and the authorization protocols were specific of my domain and they didn't respond to any known protocol, hence the custom header. Anyways, it's my own convention that probably only make sense to me.

Worth to mention that some of the largest API providers on the market still support API key authorizations and some allow us to send the key in the URL.

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

^{2: However, you will find many articles and opinions (some of them very well argued) in favour of the Authorization header.}

If you use Authorization, be consistent

Some will argue that the following is unnecessary (and not too long ago I would have agreed with them) but, these days, if we use the Authorization header we should inform the type of the token, because API keys are not self-descriptive per se ¹.

Why do I think it's necessary and why I do think it's important? Because nowadays supporting different authentication/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 app client apps whose updates were not guaranteed (mobiles and sensors mostly), I started to. I started to be more cautious in the way I implement security so that I can expand it without messing with clients and without too much pain on the server side.

Concerns

The problems I faced implementing my own schemes has 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.

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?

To my experience, implementing my own Authorization scheme has taken me the very same amount of work (or more) than implementing custom authorization headers, with the slight difference of having more freedom of design and more control over the cache when I have used custom headers. The reason is rather stupid, most of the time I have the Cache-control set to no-cache or no-store, allowing me to make the calls to the server more deterministic (this is important when it comes to tracking and testing) regardless the topology of the network.

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