Best practices for building API Keys

Hello there, we all know how valuable APIs are, its a gateway to explore other services, integrate with them and build great solutions faster.

Probably you might be having APIs or thinking to build one for other developers to use. As part of it, API needs some form of authentication to access it. There are several authentication standards available already like API Keys,

In this article, we are considering API Keys to access APIs and going to focus on how to build it right.

So Why API Keys?

API Keys are simple to use, it’s short, static, and it doesn’t expire unless revoked. Its an easy way for service to service communication

Since you are the provider of those API Keys it is essential for you to build it in a right way. Let’s get to it, and built API Keys right

1. API Keys Generation.

Since API key itself is an identity to identify the application or the user, it needs to be unique, random and non-guessable. So make sure API Key is random and long enough. Also, generate API keys using Alphanumeric and special characters like (_, -,:).

Example: zaCELgL.0imfnc8mVLWwsAawjYr4Rx-Af50DDqtlx

2. Do not store API Keys.

Hold on, I meant do not store the plain text API Key. Think about it why we need to store API keys, all we need to do is make sure that the API key in the request is valid and issued by us. We don’t need the raw key, that doesn’t mean we should encrypt and store as well. That’s not good reason is simple, it can be decrypted :)

The Right approach is to store as a hashed value

Hashed value means even if someone gets access to our database, no API keys are leaked it’s all safe. The end user should send the raw API key in each API request, and we can validate it by hashing the API Key in the request and compare it against our database. Here is a rough picture of it,

Hereprimary key will be of the format, so no need of separate prefix property

{prefix}.{hash_of_whole_api_key}

Cheers! So far so good.

But hold on, there is more, storing as hashed value bring specific usability problems. Let’s address those,

Presenting API Key to users

Since we don’t store the original API key, we can show it only once to the user, at the creation time. So be sure to alert users that it cannot be retrieved again, and they need to generate new token if they forget to copy the API key and store it safely. You can do something like,

How users Identify generated API Key later

Another problem is, how users identify the right API key in your console to edit or revoke. This can be solved by adding a prefix to the API key. Notice in the picture above, the first 7 characters (that’s our prefix), separated by the dot.

Now you can store this prefix in the database and display it in the console so users can able to quickly identify the right API key entry. Like this,