Most APIs require authentication to let you use the API. The Authentication & Authorization process allows APIs to verify your identity and decide what actions you can take using the API. In this article, I will go through four common ways of API authorization.
Table of Contents
- Difference between authentication and autherization
- Basic Auth
- Bearer Authentication
- API Keys
- JWT Tokens
- FAQ
Difference between authentication and autherization
Before we go through some of the most common ways of API authentication, let’s define Authentication, Authorization, and the difference between them.
Authentication is the process of verifying you are who you are To leave a country; you should show your passport to the customs officer to prove you are who you are. Your passport is a way to verify your identity to the customs officer; that’s authentication. In the context of the Internet, you do authentication using username/password, Single sign-on, or other forms of authentication.
Authorization is the process of verifying what you have access to. Back to our airport example, the officer allows you to cross the gate when your identity is verified. You arrive at your gate, hand over your ticket to the person in charge, and she will authorize you to board the flight.
Basic Auth
Basic auth is probably the simplest model of Authentication for APIs. To authenticate using basic auth, you should send a set of usernames & password to the API. To send the username & password, you should add the Authorization
header to your request. The Authorization
header must start with Basic
, followed by a Base64 of username:password
.
We have an API that supports Basic Auth; our username is “teddy”, and the password is “bear”.
-
First, we should get the Base64 version of
teddy:bear
(following the username:password format). The Base64 ofteddy:bear
would bedGVkZHk6YmVhcg==
-
We should add the
Authorization: Basic dGVkZHk6YmVhcg==
header to the request.
The header field might look like the following:
Authorization: Basic dGVkZHk6YmVhcg==
As you can see, exchanging your username & password with an API using Basic Auth is not necessarily very safe, so it’s essential to use Basic Auth with APIs available over HTTPS. In other words, you should never authenticate using Basic Auth for APIs over HTTP protocol..
Bearer Authentication
Bearer Authentication, also known as token authentication, is a two-step process. In this model, you, the user of an API, must first acquire a token and then use the token to authenticate & authorize your requests.
authentication servers, sometimes part of the API you want to use, are in charge of issuing a token for you. To get a token, you need to authenticate yourself first. Based on the authentication server, you may need to provide your username & password or any other form of Authentication. Once you got the token, a cryptic string, you can pass the token to the API. The issued tokens are short-lived and expire at some point.
It’s vital to use Bearer Authentication with APIs that are on HTTPS protocol. You should never send your token to an API on HTTP protocol.
To pass your token to the API, you should include it as an HTTP header called Auhtorization
. The value of this field should be in the form of Bearer {YOUR_TOKEN}
. Unlike Basic Auth, you don’t need to encode the token itself because it’s already encoded for you by the authentication server. The header field might look like the following:
Authorization: Bearer eyJhbGciOnR5cCI6IkpXVCJ9
API Keys
Authentication using API keys is very similar to Bearer Authentication, with only one difference, the way you acquire the API key itself. Unlike tokens, API keys do not have an expiry date. Moreover, API vendors generate an API key for you.
Most APIs accept API keys via HTTP request headers. However, there is no common header field to send the API key. Please consult your API vendor (or the online documentation) to find the correct HTTP header. For a more in-depth review of API keys, how to acquire one, secure, and use them, please read the What is API key article.
It’s crucial to use an API Key with APIs that are on HTTPS protocol. You should never send your API keys to an API on HTTP protocol.
JWT Tokens
JWT stands for JSON Web Tokens. As the name suggests, JWT tokens are yet another kind of token. Similar to Bearer Tokens, authentication servers issue JWT tokens upon successful logins by users. Thanks to being an open standard (RFC 7519), JWT tokens are widely adopted. As a result, there are plenty of open-source projects to work with JWT Tokens. Moreover, JWT tokens are self-contained, which means the token itself carries the claims.
When you want to send a request to an API, you should include the JWT token, usually in the Authorization
header using the Bearer
prefix. The header field might look like the following:
Authorization: Bearer eyJhbGciOnR5cCI6IkpXVCJ9.eyJsb2dnZW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSroWnFSRgCzcmJmMjLiuyu5CSpyHI
FAQ
Why do we need to do Base64 encoding for Basic Auth?
As discussed in the Basic auth section, you should include your username & password as an HTTP header. By standard, HTTP header values must only contain ASCII characters. However, your username or password may contain non-ASCII characters? Base64 encoding of the username:password
results in a string with only ASCII characters, which you can easily send to the server. The server receives the encoded string, decodes it to read your actual username & password.
How to get the Base64 encoded version of the username & password for basic auth?
Open the Developer Tool of your browser, navigate to the console tab and paste the btoa("username:password")
(replace username & password with the actual values), and press enter. Next, copy the text in the following line (without the double quotes). That’s the Base64 encoded of your username
and password
. Alternatively, you could google “Base64 generator” and use one of the websites to do it, but that’s not safe, and we don’t recommend it at all.
What is the difference between Basic Auth and Bearer Authentication?
To authenticate using Basic Auth, you will send your username and password to the API. For Bearer Authentication, you will first authenticate using a username/password (or any other form of authentication) to get a token and then use the token to authorize your request.