System Of Levers

Solving problems no one else seems to be having

Web Service API Authentication Basics

This is a very simplified overview of some Web Service API auth stuff. My main reason for writing this is to have something to point to from a future post. I'm not even remotely an expert in this area but here are some basics.

I'm not going to cover CORS. If you want an introduction to it here's a comic about it from Wizard Zines.

What Are Web Service APIs

I'm talking about APIs that you interact with over the internet using HTTP, not local ones (like a library's API). Basically a website but meant for machines instead of humans. You'll have a URL that you can make a request to and get a response. Often the response will be in JSON. For example if you make a request to https://cat-fact.herokuapp.com/facts/random you'll get a JSON object with a random cat fact! You can try it by navigating to it with your browser or if you're on a machine with curl you can run the following command:

curl https://cat-fact.herokuapp.com/facts/random

Categories of APIs

For the topic of authentication I'm going to say there are three categories of these APIs.

  1. Open/Public
  2. API-Key Based
  3. Token Based

Open/Public

Open/Public APIs are ones that are URLs that you can make requests to without asking anyone for permission. These APIs are unauthenticated and have no sense of who's accessing them, like a user or account. This means these APIs are usually for fetching data and don't give you a way of changing/uploading/posting anything. It's not usually a good idea to let the anonymous public modify your service.

The random cat-fact API is an example of an open API. It's just there, you can get cat facts whenever you want. If you want you could build an app that just serves cat facts fetched from that API. You probably shouldn't make it an important part of your infrastructure though because the cat-facts service probably doesn't have the resources for such a thing.

API-Key Based

API-key based APIs are ones that require you to have a secret value called an API-key that you either include in the request's URL, a request header, or as part of the payload. An API-key is tied to an account you have with the service and you'll usually get it from the service's website. For example IFTTT Webhooks are like this.

Once you have an API-key these APIs are basically work like an open/public API except you'll have to include the key in your request. In fact you can make any API-Key based API into a public API just by publicizing you API-key! That's probably not a good idea though since the service may revoke your key or even charge you for usage. That's one of the downsides of API-keys, they need to stay secret and you need to trust anyone you're sharing it with. Once you've shared it with someone the only way to stop them from using it is to revoke/regenerate your API-key. This will break everyone else who's using the key and you'll need to update it. For example if you've setup a bunch of ESP8266's to send requests to an IFTTT webhook. But you also shared your webhook url (with the key) with your good buddy Jerk-O. In a shocking turn of events Jerk-O turned out to be a jerk and started using it to troll. The only way to stop them is to regenerate your key and go and reprogram/update all your ESPs.

OAuth has a concept of "bearer tokens" that seems similar to an API-key.

Token-Based APIs

I'm going to be very vague here. I don't have deep understanding of this stuff. Auth is an area where mistakes can be bad and thinking you know more than you do can lead to mistakes. So if this stuff is important to you maybe find a better source than some guy's blog with two posts (including this one)!

Access tokens are a piece of data that describes access permissions to a resource. Kiiinda like API-keys! The difference tends to be that an access token has metadata that describes what it can be used to access and for how long. There also tends to be mechanism to for a user, who we'll call Jesse, who has an account on one service, say twitter, to give a token to another service, like a GameBoy twitter client, that will let the GameBoy interact with twitter on Jesse's behalf. For example to like a tweet! If you've ever been using an app or website and suddenly get a little pop-up that says "hey do you want example.com to have access to your google calendar?" with your google account photo and such then this is what's happening. It's using OAuth2 to get an access token so that example.com can access your calendar.

There also tends to be cryptography involved! The tokens will have cryptographic properties, like a signature, so that they can be verified without just needing a list of all the tokens that have been issued.