The Web API Authentication guide, The intro

As a developer, you will most likely get in the situation, where you have to decide how to authenticate your API. How would you deal with it?

If you are lucky, the auth scheme from your last project will work. Maybe you hear about a cool new technology, and you try it. Another option is doing some research and placing your bet. Maybe you knew it would work out, maybe you only hoped. Or you just didn’t give it too much thought; any is better than nothing, right?

I have been there; I know the feeling. Some years have passed, and I spent quite a lot of time on the topic. This guide is the distilled knowledge I gathered over the period. Its sole purpose is to make your life easier.

Read it, and you will confidently choose the authentication scheme next time you need to.

To help put things in perspective, I compiled a short table of contents.

This is a multi-part series as we have a lot of ground to cover. I divided the topic into three chapters. The first one, which you are currently reading, is about the framework I will use for comparing the schemes. In chapter two, I discuss commonly used solutions. Finally, you will receive a small cheat sheet and some closing thoughts.

I will publish a part every other week. Be sure to subscribe so that you won’t miss them!

Let’s get started!

I. What to look for in an authentication scheme?

A bit of a disclaimer

Authentication is a huge topic. Let me zoom in on the part we are dealing with throughout the guide, and that is requests.

APIs deals with requests. Anything that follows is about authenticating requests and not humans/users. It makes perfect sense to distinguish between these two, after all, you wouldn’t try to validate a request based on its biometric properties, right? Or offer it a one-time code via SMS?

Points of interest

CC0 image by Matheus Bertelli

Authentication schemes are kind of like shoes. I know it sounds silly, but bear with me. There is a shoe for every occasion. Some are elegant and fit well for a casual evening; others keep you warm in the winter and cool in the summer. Some can take you hiking and keep the water out.

Shoes are manufactured for a specific purpose, just like authentication systems are designed for a particular use-case.

What distinguishes shoes from each other are its features: looks, lining, water resistance, price, etc. This is no different in the case of an authentication scheme.

So what are the features of an auth scheme?


Complexity is a major factor. A simple system has fewer problems. To make this more transparent, I will discuss how each mechanism works and judge its complexity based on how hard it is to implement the scheme. To keep things simple, I will place the solutions in three categories: easy, medium, hard. While this does not tell much about the scheme by itself, they are perfect for comparison.

Reliance on HTTPS

HTTPS is using the HTTP protocol over TLS. TLS is the protocol the provides some strong security properties. It is most well known for providing confidentiality, i.e., encryption of traffic. Making it impossible for anyone intercepting the communication to learn its content. What is lesser known is that TLS also provides integrity and replay protection. More on these later.

This factor deals with how well can the given authentication scheme function if it is not deployed over HTTPS or some properties of TLS do not hold.

CSRF protection

CSRF stands for cross-site request forgery. It is a common vulnerability which greatly affects authentication as well. It happens when a malicious website can initiate requests to your API, and the browser will attach a logged in user’s credentials automatically. Backend use-cases are not affected.

Some auth schemes are protected by design, while others require manual effort to defend against this type of attack.

Try it in practice

Any protection against web based attacks is easier to understand when you see it in action. While this guide gives you a great overview about web authentication, you can learn even more about the topic by trying it yourself.

Replay protection

What if an attacker could record the requests to your web application and play them back at his will? Ideally, a request should not be processed if it is being replayed by a third party. Makes sense right? Would the authentication scheme stop our adversary from doing this? Some do, and it’s worth to know which ones.

Integrity protection

HTTP requests travel through lots of parties before reaching the server. A malicious party should not be able to modify our authenticated request. Imagine if this wasn’t so. An active man in the middle could overwrite the requests and gain complete access to the API with the given credentials.

A shoe for an occasion and an auth scheme for a given use-case. Some are good on the frontend while others are backend only. A few can be used in both scenarios. I propose use cases where the given scheme is the preferred solution. This section will help you make the smart-tradeoffs you will benefit the most from.

This section is by no means a rule book. After all, you can wear sneakers to a wedding. And sometimes it will work out just fine.

Taking care of your auth scheme

I will provide you with tips on what to look out for when using the system. Be sure to apply these practices and it will prolong your authentication scheme’s life considerably.

Coming up next

Now you know what to look for in an authentication scheme. I encourage you to take a look at the system you are currently using and with this perspective.

The next post in the series deals with the simplest authentication scheme of all called HTTP Basic. Have you ever heard of the following phrase?

“I’ll just throw Basic Auth on my API, and I will be fine, right?” - a dev while smiling.

The comments he receives fall into two categories. “Yeah, right” and “Are you serious? Basic Auth is for kids!” Which one is correct? Subscribe and keep an eye out for the next post to find out!

Have I missed something? Please don’t keep it to yourself, correct me in the comments! I will appreciate it.

comments powered by Disqus