Matt Ledger
Matt Ledger
January 23, 2018

How API security works

Proper API security checks users in and provides them with limited access to your system, just as a concierge does for guests at a hotel. Let me explain.

The larger process of API security breaks down into five subprocesses: identification, authentication, authorization, delegation, and federation. Secure APIs perform each of these tasks whenever a user attempts access. Together, these tasks allow an API to verify a user is who they say they are, determine what functions the user has access to, and give the user access to those functions for as long as they’re verified. A hotel concierge follows exactly the same set of processes when checking guests in to a hotel.

When the concierge asks a new guest to provide her name as she steps toward Hotel API’s check-in counter, that’s identification. Identification allows the concierge to look up the guest’s name and determine whether she has a reservation. Or, in the case of our API, determine whether our user’s actually a legitimate user. Most often, this identification is accomplished using API keys ( Application programming interface key). You’ll note our concierge hasn’t actually allowed our guest access to the hotel yet. He’s first checking to make sure she’s even supposed to be there in the first place. If she isn’t, our concierge will toss her out.

Before our concierge allows our guest into Hotel API, he’s going to make her prove that she is who she says she is. That’s authentication. In our check-in example, authentication often takes the form of the new guest providing her credit card and driver’s license to the concierge. The concierge checks these items over to make sure the guest’s ID is legitimate. API authentication can take many forms. Often, it requires just a username and password. Increasingly though, authentication requires some sort of time-sensitive, single-use token that’s been passed to the user. The important part is, this is where our API verifies the user’s identity.

After that, the API looks up exactly what functions the verified user should have access to. That process is called authorization, and it’s akin to our concierge figuring out what kind of reservation his new guest made. If she reserved a room with a King size bed, she should be given a room with a King size bed. She should not be given a room with a Queen size bed, and she most assuredly should not be given the Hotel API’s luxury suite. She should also not be let into the hotel staff’s breakroom. According to the terms of her reservation, our guest should be allowed to access her own room, the hallways and elevators, the pool, the exercise room, and the hotel lobby. And that’s it. In much the same way, API authorization ensures a user doesn’t gain access to data or functions outside what they’re allowed, ensuring no mischievous hacker gets too far into your system.

From here, the API security system gets slightly more complex, but our check-in example continues to apply. Let’s imagine a world where our hotel guest had to check in with the concierge every time she wanted to perform an action. Going to her room? Check in with the concierge. Going to the pool? Check in with the concierge. Taking a run on the treadmill? Not before you check in with the concierge. That sounds pretty tedious, right? To avoid this constant need for re-verification, APIs use a process called delegation. At the Hotel API, delegation takes the form of the room key the concierge hands our guest at the end of the check-in process. With her room key in hand, our guest is automatically allowed to do any of the actions our concierge okay’d her for at check-in. The key acts as a constant physical token of her authorization. In our actual API world, this sort of API-granted token prevents the need for additional, repetitive logins to perform previously authorized actions.

Federation, on the other hand, is more akin to a Loyalty Card the concierge asks our guest to sign up for as she checks in. The Loyalty Card gives our guest clout at the other Hotel API locations throughout the world, allowing her to quickly prove her identity and allowing other concierges to look up her information. Organizations that provide one API or API-based service often provide multiples. Federation allows for Single Sign-On across all these services, much like the Loyalty Card proves our guest’s ID and access-level at all Hotel API locations. There are other benefits to federation, such as creating another barrier between users and the resources they’re attempting to access. But for our purposes, this Loyalty Card analogy will serve for now.

So there you have it: the process behind ideal API security. But now that you understand the process, how do you actually implement it? In the next part of this series, we’ll get into the weeds of how you incorporate API security into your own APIs.

(This post is part 3 of our Basics of API Security series. To start reading this series visit: The Basics of API Security - The Intro)

With Thriftly, we handle API security for you. Get started building simple, secure web APIs today with a free trial.

New Call-to-action