Defining an effective authentication method for API requests

Vers?o em Português

Authentication is necessary on a lot of services now-a-days. Simple stuff like downloading shared files is tied to an authentication flow, even if it's passwordless. We live in the time of customized experiences and targeted campaigns of all kinds, which makes it necessary to identify who is in the other side of servers and apps: our most beloved consumer.

When talking about API consumption your target audience won't be using a browser to interact with your services, actually, most of the time you'll have no idea which kind of system is receiving your information. Because of that, authenticating API requests is a different process than for common web applications. In this scenario you can't rely on simple features like cookies, local storage or redirection flows, that all browsers have.

There are 4 commonly used standard authentication methods for API requests. You will most definitely see them being used by a lot of major players in the industry, in a way or another.

HTTP Basic Authentication

This one gets close to what a browser user understands as authentication. Your username and passwords credentials are hashed into Base64 and sent as an HTTP Header to the server with every authenticated request and Base64 hashes are easily decoded. What is notable is that your clients' credentials get passed as decryptable text, which is a security risk.

The threat gets worse if the authentication credentials used on your API could be used on other parts of your system. This kind of authentication gets safer on the web when using TLS encryption enforced by HSTS. Because of that it's mainly used on IoT and intranet implementations.

Aside from that it's fairly easy to deliver and it only adds a little overhead to every request. Your system would need to decode the Base64, check the (hopefully) encrypted password against your database and only then send the request back.

API Keys

API Keys are an evolution of Basic Authentication. The authentication process takes place in the same kind of flow, but the Authorization HTTP Header contains the API key instead of a username/password combination. API keys are used only in some parts of your application and are not tied to any kind of sensitive information about the client itself. This opens the possibility of expiring API keys from time to time manually or automatically.

JWT - JSON Web Token

This is where API authentication begins to get interesting... JWT is flexible, but sometimes not the most efficient alternative when compared to other methods. We’ll see why in a second.

JWT authentication flow starts with some kind of login endpoint, where the server identifies the client and assigns a token to it, containing some security headers, a payload with information about the user and a signature, which guarantees the authenticity of the given token through asymmetric encryption.

In fullstack web frameworks this would be a bad idea, because you'll most likely hit the database in every request for other information about the user in any given page, bloating your requests with headers and crypto for something you'll have to validate or DB query anyway. But for API operations this amount of "session info" is awesome!! Not only you are sure the tokens are legit (thanks to crypto signing), you can also get info in in a stateless manner, giving your database a break across all requests.

OAuth 2.0

You may have already used this kind of authentication on many websites. This is known as a passwordless authentication, mainly because you may not even have a password assigned to your client to make them able to login into your application. OAuth is actually an authorization method, but it does have an authentication flow attached to it. It resembles the JWT flow, but with a kind of application layer of it's own - this is what enables the use of this kind of authentication on third party websites.

The flow starts with an authorization request to the resource owner, which is done through the application layer of the OAuth 2.0 flow. The resource owner will then evaluate if the application is valid to login and if the credentials are OK, returning an authorization grant, which can be a kind of API key or an JWT. With this key in hand, the server does another request to retrieve an access token, defining the scope of the resources that the current application has access to.

This is as awesome as JWT, because you have the same kind of stateless behavior containing data about the requester, and a bonus if you use third party authentication like "login with <insert social media>" . This kind of authentication almost feels like you don't even have an authentication in your own server, but it's a little hard to implement yourself. Because of that there is already a lot of OAuth 2.0 libraries in virtually all web languages - even client side ones.

So, how do I decide which one to pick?

Deciding which one is more adequate for your system can be tricky. There are some factors to weight on deciding an effective API authentication method.

1. Performance - Some authentication methods can be cumbersome to your performance. That can be because it's highly dependent on crypto or just plainly full of complex/numerous checks.
2. Security - This is key for a reliable authentication, and where you see the most flexible behaviors across systems. Mainly because the kind of security for an IoT solution shouldn't be implemented on a public web API, but it could be implemented on an intranet system.
3. Complexity - Sometimes automatic token rotation is poorly documented and your clients get confused about their session being constantly revoked. Implementing your own OAuth service can be difficult for some and dealing with crypto or JWT implementation is challenging.

You can choose a method beyond the ones in this article or even build your own kind of authentication flow. It's up to you! So which is your weapon of choice when it comes to API authentication? Leave your experiences in the comments, I'd love to hear it from you.