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?

  • The projects under my guidance use Authorization: Bearer <token> header and there was never a single issue with that. The tokens are JWTs. – Andy Jul 20 '17 at 15:20
  • 1
    @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 Jul 20 '17 at 20:13
  • @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. – RomanG Jul 20 '17 at 20:13
  • 2
    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. – Andy Jul 20 '17 at 21:05
  • 1
    (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 – K. Alan Bates Nov 30 '17 at 3:10

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 1.

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.


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.


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

  • 4
    The using of X- is deprecated as of 2012: stackoverflow.com/a/3561399/923720 – Darkhogg Jul 20 '17 at 14:26
  • 1
    ops! I didn't know. Edited and fixed. – Laiv Jul 20 '17 at 14:34
  • 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/… – user949300 Nov 29 '17 at 22:36
  • 1
    @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. – K. Alan Bates Nov 30 '17 at 3:18
  • @K. Alan Bates Most of my API interactions have been for relatively "unimportant" things like free tiers of geocoding, weather reports, and the like, where the API key is more for rate limiting than serious user secrets. So, as for OP, depends on what level of security is needed. – user949300 Nov 30 '17 at 5:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.