- Guides
- An introduction to APIs
- Authentication, part 1
Chapter 4: API authentication, part 1 (basic vs. key)
By Bryan Cooksey • Published April 22, 2014
Things are starting to pick up in our understanding of APIs. We know who the client and server are, we know they use HTTP to talk to each other, and we know they speak in specific data formats to understand each other. Knowing how to talk, though, leaves an important question: how does the server know the client is who it claims to be? In this chapter, we explore two ways that the client can prove its identity to the server.
What is API authentication?
You've probably registered for an account on a website before. The process involves the site asking you for some personal information, most notably a username and a password. These two pieces of information become your identifying marks. We call these your credentials. When you visit the website again, you can log in by providing these credentials.
Logging in with a username and password is one example of a technical process known as authentication. When you authenticate with a server, you prove your identity to the server by telling it information that only you know (at least we hope only you know it). Once the server knows who you are, it can trust you and divulge the private data in your account.
There are several techniques APIs use to authenticate a client. These are called authentication schemes. Let's take a look at two of these schemes now.
Basic authentication
The logging-in example above is the most basic form of authentication. In fact, the official name for it is Basic Authentication ("Basic Auth" to its friends). Though the name has not garnered any creativity awards, the scheme is a perfectly acceptable way for the server to authenticate the client in an API.
Basic Auth only requires a username and password. The client takes these two credentials, smooshes them together to form a single value 1, and passes that along in the request in an HTTP header called Authorization.
The Basic Authentication process involves combining the username with a colon, followed by the password, and then running the whole string through the base64 encoding algorithm. Thus "user" and "password" becomes "user:password" and, after encoding, you have "dXNlcjpwYXNzd29yZAo=".
When the server receives the request, it looks at the Authorization header and compares it to the credentials it has stored. If the username and password match one of the users in the server's list, the server fulfills the client's request as that user. If there is no match, the server returns a special status code (401) to let the client know that authentication failed and the request is denied.
Though Basic Auth is a valid authentication scheme, the fact that it uses the same username and password to access the API and manage the account is not ideal. That is like a hotel handing a guest the keys to the whole building rather than to a room.
Similarly with APIs, there may be times when the client should have different permissions than the account owner. Take, for example, a business owner who hires a contractor to write a program that uses an API on their behalf. Trusting the contractor with the account credentials puts the owner at risk because an unscrupulous contractor could change the password, locking the business owner out of their own account. Clearly, it would be nice to have an alternative.
API key authentication
API key authentication is a technique that overcomes the weakness of using shared credentials by requiring the API to be accessed with a unique key. In this scheme, the key is usually a long series of letters and numbers that is distinct from the account owner's login password. The owner gives the key to the client, very much like a hotel gives a guest a key to a single room.
When the client authenticates with the API key, the server knows to allow the client access to data, but now has the option to limit administrative functions, like changing passwords or deleting accounts. Sometimes, keys are used simply so the user does not have to give out their password. The flexibility is there with API key authentication to limit control as well as protect user passwords.
So, where does the API key go? Unlike Basic Auth, which is an established standard with strict rules, API keys were conceived at multiple companies in the early days of the web. As a result, API key authentication is a bit like the Wild West—everybody has their own way of doing it.
Over time, however, a few common approaches have emerged. One is to have the client put the key in the Authorization header in lieu of a username and password. Another is to add the key to the URL (http://example.com?api_key=my_secret_key). Less common is to bury the key somewhere in the request body next to the data. Wherever the key goes (assuming it's located where the server expects it to be based on the API documentation), the effect is the same—it lets the server authenticate the client.
Chapter 4 recap
In this chapter, we learned how the client can prove its identity to the server, a process known as authentication. We looked at two techniques, or schemes, APIs use to authenticate.
The key terms we learned were:
- Authentication: Process of the client proving its identity to the server
- Authorization: Process of the client proving its access privileges
- Credentials: Secret pieces of info used to prove the client's identity (username, password...)
- Basic Auth: Scheme that uses an encoded username and password for credentials
- API key auth: Scheme that uses a unique key for credentials
- Authorization header: The HTTP header used to hold credentials
Next
In the next chapter, we continue the discussion of authentication by looking at a third technique; one that is quickly becoming the standard of the web.
Published April 2014; last updated January 19, 2024
Previous chapter:
Next chapter:
