Home / GitHub Page

API token as header

#1

I would like to propose the possibility to send the token via a header.
Maybe this is just a personal preference, but I always thought that tokens are better sent in the header than in the GET request.

I would change the code in that way that if the token is present in the header, no token is needed in the GET request. The token would still be valid in the GET request though.
However, we have to decide which would take precedence when both are used at the same time. In that case I suggest the token in the GET request wins.

In any case, my change would not alter the default behavior nor break anything.

What do you think?

1 Like
#2

on my side I don’t have a fixed idea, but the topic has been discussed here, and a RFC says HEADER

#3

I’d be fine with it but then I’d like to deprecate the GET method, as I prefer not to keep accumulating multiple methods to do auth.

That means we’ll need to update the documentation to use the header method instead, and eventually remove the GET query parameter. We can put a warning on the doc that the GET query parameter is deprecated and will be removed in 6 months for example. After 6 month, using the GET query parameter will print an error with a link to the doc.

Let’s use something standard for the header as described there: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization

For example:

Authorization: Token 123456781234567812345678123456781234567812345678

I see there’s a list of authentication type: https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml But I couldn’t find a simple summary of it so not sure if any of these would make sense for us.

#4

Seconded.

#5

It was certainly not my intention to deprecate the GET parameter and make it harder for people who already use the API.

Using the Authorization header is probably not a good idea. This header is mostly used by the web server and not the application on top. AFAIK, there’s no Authorization: Token xxxxxx format either and I have never seen a token used in that way (except OAUTH which is a different story).
We could write an RFC and submit it, even though I doubt it makes much sense, because most people would rather manage the tokens in the application layer than the web server.

In the APIs I wrote, I used the header TOKEN: token-here, but I’ve seen different names like API-KEY, APIKEY, APITOKEN, API-TOKEN, …

This topic is rather complex, because tokens are not supposed to be used as a security measure alone, but used in combination with an authorization scheme. Some even use a token instead of the password for basic authentication. But I think we can forego an endless discussion about the principles of token utilization. (It does not apply to us anyway.)

We don’t use authorization at all, so we only have to decide on a HEADER name.

The reason why I use TOKEN is the following: it is succinct and self explanatory. e.g. what else would be the header TOKEN for when you connect to an URL https://example.com/api/v1/endpoint? Developers who use an API know that they need a token, so there’s no reason to use an API prefix for TOKEN. However, I’ve heard the argument that there could be more than just one token, in which case the prefix were to help with distinguishing them. Valid point, but we don’t, thus no need. :wink:

#6

I know (and use) several rest API’s that use the Authorization header. It is meant for this.
E.g. Spotify: https://developer.spotify.com/documentation/general/guides/authorization-guide/ (see steps 2 and 3).

#7

I don’t think there’s a case to support multiple auth methods. If a header is the correct way to do that as seems to suggest foxmask and sciurius link then maybe we should switch to this. But having two methods doesn’t make much sense and makes maintenance more complex.

As for the exact format, I’ve also seen things like X-SOMETHING: token-here

#8

Yes, but those APIs provide authorization from the backend. You just made my point exactly. This does not apply to Joplin. There is no authorization in Joplin. The method described is more like OAUTH + API token, therefore 2 tokens. In joplin, we have one token.