Authenticating your RESTful API

Article 8 in the series of “ Pragmatic decisions for your RESTful API”, this post talks about authentication for your RESTful API.

Authenticating users: use OAuth 2 and/or JSON Web Tokens with the Authorization HTTP header

User authentication for a RESTful API could (and maybe will) be the subject of another series of articles, given how wide and complex it can be. To summarize it very briefly however, there are currently 2 technologies you can use for user authentication:

  • OAuth 2 (which can be combined with OpenID Connect)
  • JSON Web Tokens

Both of these methods will basically exchange an authorization (for example, a user entering their email and password and saying explicitly that they trust your API) for a token. This token will then need to be sent with every API request by your client.

The token can be sent in multiple ways, via a query parameter, the request payload or an HTTP header. The recommended and most secure way is to use the Authorization HTTP header, and send it in the following way:

Authorization: Bearer <token>

Why you should not send your token as a GET parameter ?

It could be very tempting to design your API to allow users to receive tokens via a GET parameter, with for example the following request:

GET /my-resource?access_token=123456

The main issue with this is that the access tokens of your users will most probably end up in your logs, which is bad practice in terms of security (as if an attacker somehow gains access to your logs, he will also get access to many access tokens).

You can easily avoid this issue by designing your API to receive tokens only via the Authorization header.

Authenticating applications: use API keys

Again, the whole topic of API authentication is very large, and this report will not go into details, but basically, if you want to authenticate other applications (in other words, allow not only users but also other applications to use your API), your API should provide a mechanism for generating API keys. As a tip, think that these API keys can actually be JSON Web Tokens.

These keys will then need to be sent in the “Authorization” HTTP header, in the same way that user authorization tokens work.

If you want to read all of the articles of the series “ Pragmatic decisions for your RESTful API”, you can start here. The next article will focus on designing the relationships between resource in your RESTful API.

If you need it in a handy format, this series of articles is also available as an eBook on Amazon.

Originally published at on March 30, 2018.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store