Place API key in Headers or URL

Question

I'm designing a public API to my company's data. We want application developers to sign up for an API key so that we can monitor use and overuse.

Since the API is REST, my initial thought is to put this key in a custom header. This is how I've seen Google, Amazon, and Yahoo do it. My boss, on the other hand, thinks the API is easier to use if the key becomes merely a part of the URL, etc. "http://api.domain.tld/longapikey1234/resource". I guess there is something to be said for that, but it violates the principle of the URL as a simple address of what you want, and not how or why you want it.

Would you find it logical to put the key in the URL? Or would you rather not have to manually set HTTP headers if writing a simple javascript frontend to some data?

Lyn

Answer 1

It should be put in the HTTP Authorization header. The spec is here https://www.rfc-editor.org/rfc/rfc7235

Dilatometer

I already use the Authorization header for the third part - the end user. That is the end user needs to log in to the app to gain full access to the content. – Lyn

@Thomas There is no limit to the number of parameters you can put in the auth header. Look at OAuth it has about 8 different parameter values in the header. – Dilatometer

Link update — This is now RFC 7235 as of June 2014 – Wilscam

I'm not saying you're wrong, but when you say "It should be"--how do you know? Who says? (I found this question because it seems Apache often strips the Authorization header before PHP beings to execute) – Corydon

@Corydon I go into more details here bizcoder.com/where-oh-where-does-the-api-key-go I'd be interested if you have any links to the Apache issue. – Dilatometer

@DarrelMiller thanks for the link. I agree it's better in the headers than the URL query string (or pseudo path, etc), but I was hoping there would be some sort of definitive direction from an authoritative body on which header should be used. My Apache issue is currently anecdotal, so I don't have any links to offer in return. I am leaning towards using something like X-API-KEY at this point. – Corydon

@DarrelMiller Checkout this note in the code for Symfony's HTTP Foundation: github.com/symfony/http-foundation/blob/master/… – Corydon

@Corydon Well there is RFC 7235 which is an entire spec on how to do HTTP Authentication and the only option it presents is using the Authorization header. – Dilatometer

@Corydon and the github link does say that it is the php-cgi module that does not pass the basic auth header, not Apache itself. That's probably because php-cgi probably does authorization itself and doesn't want to pass clear text passwords down to the application. – Dilatometer

Answer 2

If you want an argument that might appeal to a boss: Think about what a URL is. URLs are public. People copy and paste them. They share them, they put them on advertisements. Nothing prevents someone (knowingly or not) from mailing that URL around for other people to use. If your API key is in that URL, everybody has it.

Susa

In addition to your points about public disclosure of a URL, the URL and an in-line API key would be visible to all network administrators with access to a router, corporate proxy server, caching server, etc. – Aha

@AdamCaviness Not with HTTPS, which all APIs should implement anyway. URL is encrypted. As an admin you can only see the DNS lookup and the IP address communicated with, not the content. That aside I agree with stand – Snowonthemountain

@nickdnk, that's true. Now concerning HTTPS, even then, full URLs remain in browser histories! Fun stuff. I'm not a fan of anything sensitive being in a URL. – Aha

@AdamCaviness Yeah, in that sense. I understood it like someone could read the traffic if they had access to the router. – Snowonthemountain

API key in the URL also means it could end up in various logs too. – Hepatitis

Answer 3

It is better to use API Key in header, not in URL.

URLs are saved in browser's history if it is tried from browser. It is very rare scenario. But problem comes when the backend server logs all URLs. It might expose the API key.

In two ways, you can use API Key in header

Basic Authorization:

Example from stripe:

curl https://api.stripe.com/v1/charges -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password).

Custom Header

curl -H "X-API-KEY: 6fa741de1bdd1d91830ba" https://api.mydomain.com/v1/users

Masquer

Why X-API-KEY? Is this X a kind of HTTP specification for custom headers? – Violate

stackoverflow.com/questions/3561381/… – Masquer

Answer 4

passing api key in parameters makes it difficult for clients to keep their APIkeys secret, they tend to leak keys on a regular basis. A better approach is to pass it in header of request url.you can set user-key header in your code . For testing your request Url you can use Postman app in google chrome by setting user-key header to your api-key.

Nicotine

How are api keys in parameters making users leak their keys? – Breadstuff

Server logs as well as layer 7 proxies could log the URLs to plain text flat files. You may however argue that they could log the headers as well, but that is less routine compared to the URL. Other than that, I cannot think of any reason why header is less leaky than the URL - otherwise they are equal in all respects... – Cherin

Answer 5

I would not put the key in the url, as it does violate this loose 'standard' that is REST. However, if you did, I would place it in the 'user' portion of the url.

eg: http://[email protected]/myresource/myid

This way it can also be passed as headers with basic-auth.

Metrical

Note 1) this is just shorthand for basic auth, 2) not all HTTP clients will honor it, and 3) at least one major browser will show a phishing warning. – Paterson

@Paterson Points taken. In response: 1) I eluded to that in my last sentence, 2) This is mentioned in the standard (tools.ietf.org/html/rfc3986), so that's the fault of the client, 3) I was not aware of that, though I suppose it makes sense, I wonder if this is still the case when used as an api-call (XHR). Finally, the question was about including auth-info in the url in a restful way, and I think I answered that. – Metrical

Answer 6

It depends of the data.

If the user will provide the data, put it in the url.

If you provide the data, put it the header.

Ila