(This article originally appeared on Bearer.sh)

As you begin working with third-party APIs, you'll run into a variety of API authentication methods. The three most common methods to perform authenticated requests with an API are:

1. Basic authentication: You send your username/password alongside every API call 🏴‍☠️
2. API Key: The service creates a unique key for your account and you pass it alongside every request 🤓
3. OAuth: A user clicks on a sign-in button, grants permission, and your app can authenticate each request with an access_token 🚀

Each method has its own pros/cons.

• Basic is very easy to implement, but would you give your Google account password to someone? (You shouldn't!)
• API Key is as easy to implement, both for the API provider and the developer. But have you ever tried to ask a non-techie to give you its API key?
• OAuth (especially OAuth2.0) is the best in terms of user experience. Your users click on a button and that's it. But for developers, implementing an OAuth dance can be tricky!

Even if you don't use many APIs, you are likely to encounter all three methods. For example, Mailchimp and Twilio use a basic authentication method. Stripe or Sendgrid have preferred dealing with API Key. While Google, Facebook, and Twitter mostly use OAuth.

If you are using some exotic APIs, you might also discover other methods (like JWT or custom ones). As they are less common today, I'm going to focus on the other ones.

Basic

The basic authentication, as we use it today, is 20 years old 🥳 Officially standardized in June 1999, it has been very largely implemented and all browsers still support it out-of-the-box (even IE).

It works by passing an Authorization header alongside the request:

curl "https://example.com/" \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="

The string Basic indicates that we are using basic access authentication. And the string dXNlcm5hbWU6cGFzc3dvcmQ= is a base64-encoding of username:password.

It's not mandatory to pass a username and password here. For example, Twilio uses [YOUR ACCOUNT SID]:[YOUR AUTH TOKEN].

API Key

The API key is a secret that the API generates and gives to a developer. It is generally a long, unguessable string like: 3580944e0b742e664d10a5ed75f0bdbe.

Contrary to the basic authentication, there's no standard on the API Key. The most common pattern is to pass it alongside the Authorization header:

curl "https://example.com/" \
  -H "Authorization: 3580944e0b742e664d10a5ed75f0bdbe"

But some APIs ask developers to pass it in as a dedicated header X-Api-Key, as a query string https://example.com/?key=3580944e..., or even in the body { "key": "3580944e..." }.

What's great with API Keys is that id adds granularity to the API. One of the champions in that category is the Stripe API, which on top of a "master" API Key, allows developers to create "restricted keys" that can provide more specific access, like "read-only".

OAuth

Introduced in 2007, OAuth has a strong focus on the user experience. The core concept of OAuth is that the end-user doesn't share any credentials with the third-party application, i.e. the developer.

Whilst the UX is clearly the best with that authentication method, it's sometimes tricky for a new developer to start with.

There are two reasons for this. First, there is not one-way of doing OAuth, but 5:

• OAuth1 (which has been revised to OAuth1.0A);
• OAuth2.0 which proposes up to 4 grant types.

Second, it introduces several concepts at once. For instance, it requires to first request an access_token, then it can start to perform API calls, but only for a limited period of time because it needs to refresh that token.

But once you have become an OAuth master 👩‍🎤, you'll see that it looks familiar:

curl "https://example.com/" \
  -H "Authorization: Bearer {access_token}"

Takeaways

Of Basic, API Key and OAuth, which can you expect to see most often?

We surveyed 100+ APIs monitored at Bearer.sh and OAuth is the most widespread method 🥳.

📢 The most common API authentication methods was originally published on the Bearer blog.