What do API Keys REALLY do?

TIL the true purpose of API keys: a simple yet important revelation!

Some definitions for overloaded terms that I will be using in this post:

Client = application built on top of public APIs. User = A user of that Client app, that has an Identity registered with the public APIs.

and a tl;dr for those who don’t want to read more:

• API keys identify a client application that is authorized to use the APIs.
• Authentication identifies a user to the APIs, so the API can return relevant data.

The problem

This week at work, we ran in to some tricky system design questions about where pieces of user identification should live for a system of APIs we support.

We wanted to expose these APIs publicly, so interested users could build applications on top of them that provide additional business logic or different views than what we provide by default.

These APIs were authenticated using Auth0. A user who attempted to access the APIs needed to identify who they were via an authentication request, so the APIs could perform role based authorization on future requests for data. The authorization is critical to ensure that users are only seeing data they are permitted to see.

Additionally, we wanted to ensure that the APIs were not subject to DDOS attacks, and we wanted to set limits on the number of requests clients could make per day.

The solution? Stick the APIs behind an API Gateway which would perform rate limiting / request throttling on incoming requests. The gateway issues interested parties an API key, which identifies that requestor to the Gateway so it can keep track of it’s request behavior.

But what’s in an API key? What does this key, issued by the api gateway, really tell us about the requestor?

API Keys Are for…

Think about times you’ve used API keys in the past… for Twitter, Facebook, Google APIs… you request an API key, go off and build an app on top of those APIs, and you forward the API key in all requests to those APIs from your app.

We realized the from your app piece was critical: an API key is meant to identify a client app that is using the APIs. In other words, an API key identifies a particular client of the API, but tells nothing about the permissions or authorizations of a user of that client.

API keys can contain information about which resources of the public API a client is able to access.

For example, maybe a user is building a client that leverages Google maps data. Their API key might permit them to access maps data, but the same key wouldn’t allow them to access calendar.

A client that wanted to access calendar data could either request a different API key that permits calendar access, or they could request to extend the permissions of their maps key to also permit calendar.

Either of these solutions is possible through configuration in the API Gateway.

So what about user identity?

If an API has a sense of user identity, and returns different data based on the permissions of the requesting user, a user of a client app should also be required to authenticate with the API to identify themselves.

This is possible to do through the client app, by offering a login page that makes the authentication request to the underlying APIs.

A public client app built on top of public apis could be accessed by anyone in the world, in theory. This is why it is critical to force the users of those apps to identify themselves to the underlying APIs, to ensure they are shown the correct data.

I hope it is clear from this example that user identity information should NOT be assumed in an API key. An API key is just requested by a single person (generally the developer who is creating the app) so it is truly impossible and improper to attempt to identify users through an API key.

Recap

So to recap:

• API keys identify a client application that is authorized to use the APIs.
• Authentication identifies a user to the APIs, so the API can return relevant data.

Clarity, thy name is API key!