We’ll start with the standard definition:
An API key is a string of characters used to identify and authenticate an application or user who requests the service of an API (application programming interface).
In this article, we break down this definition for the curious folk (tech or non-tech) who want to know the inside story of what an API key is and does, and how it works.
An API key is a Secret Code That Gets You Inside
Identification and Authentication
An API key is the standard security mechanism for any application that provides a service to other applications.
While they are not the only method (APIs can use JWT, which we wrote about here: API keys vs JWT auth), API keys are the most-often used method of securing an API.
The Google Maps API is an example of an API service (“endpoint”) that requires an API key. If you give Google’s API a physical address (say “1001 Main Street, NY, NY”), the API will return the latitude and longitude of the most likely location (40.736124774992504, -73.82508447321075).
However, without a valid API key, Google won’t answer your request. You need special permission. The API key lets Google know who you are and whether you have the right to access their map service.
This is called authentication (as opposed to authorization, which we discuss later in the article.)
By the way, just to understand how the mechanism works, when we write, “We give Google’s API an address”, or “We send Google an API key”, we’re referring to sending information to a Google server (making a request through HTTP request methods like Post and Get) and receiving information back (getting a response from the same API).
In sum:
If a developer wants to create a map application using Google’s near exhaustive list of world addresses, they will need to first sign up with Google and obtain an API key to have the right to use their Google Map API service.
Not all APIs Require or Use API Keys
Some APIs don’t require an API key. For example, the Youtube URL that you use to watch a video is actually an API request that does not require an API key.
It’s free to use from anywhere in the world, on any device, by all people (not just developers).
That said, Youtube’s APIs also offers other services that require an API key, such as those that give (private or usually paid) information about channel playlists, comment history, usage statistics, and hundreds of other Youtube-owned data.
Ease of Use: API-First Thinking
One central concern with any API is its ease of use. As we’ll repeat below in the context of security: ease of use is paramount to API usage.
All API-first companies want to minimize all friction in using their API products. This includes making access to their APIs easy and secure, which is exactly what API keys are designed to provide.
API Keys – How They Work
As described above, an API key enables a server to identify any developer or application (the requestor or user) attempting to access its service(s).
An API key also defines a set of access rights. Access rights authorize the requestor to take specific actions and forbid it from taking other actions.
Let’s get into the details.
Your API Key is a Unique Identifier, Usually a Long String of Characters
Your API keys are unique identifiers made up of a combination of numbers and letters. Some also contain non-alphanumerical characters.
The unique identifier doesn’t signify anything on its own; it’s only meaning is its uniqueness. It’s akin to a password or secret code.
API keys usually contain over 64 characters and are generated by system randomizers that create universal unique identifiers (often called GUIDs).
Getting Access: Authentication or Failure
Think of an API key as a way of getting access to the data and functionality of an application via an API.
Every API requestor sends the server a unique identifier, which the server uses to determine (authenticate) if the person or application requesting the service has a right to do so.
If the server can’t authenticate the requester of an API call (request), it sends back a failure response. This is the basic idea behind why you create an API key: if you’re using a key that the server doesn’t recognize, then you won’t be able to use the service.
However, if the server does recognize the API key and authenticates the holder of the key, then that user has the right to use the service.
The next step is for the server to authorize the requestor to do one or more things.
Authorization
The authorization process determines a requestor’s rights and scope. Authorization defines the exact manner in which an authenticated requestor can use an API.
It involves defining your rights (what functionality and data you can access) and scope (how much data, how long you can use the API, and more).
Rights
The rights are about what you can do. If the requestor’s API key contains the right to search the data, then the requestor can read the data to perform the search.
If the requestor has the right to write data, then the requestor can perform some or all write operations. Write access usually comes with more detail. For example, the requestor might have the right to update an index but not delete records.
You can also combine rights. For example, a requestor might have both read and write capabilities, or just read-only. Typically, requestors have several APIs to perform different actions. For example:
Read-only for searches.
Read & Write access for browsing as well as indexing (adds, updates, deletes).
Admin access, which includes everything, including creating other APIs.
Admin Rights
Every API system has a global API key that not only allows read & write operations, but full access to anything else an API can do.
For example, an Admin API allows applications and users to take meta actions like adding, removing, or modifying users, identifiers, rights, and scopes.
Given the power of an Admin API key, you’ll want this API key to be completely secure – that is, hidden and locked-away from the public.
The same applies to any write-level API key. Read-only keys may be more flexible depending on the use case. Reading business-sensitive data obviously needs higher security than searching products and film on a website.
Scope
Once a requestor has a right to do something, an API can restrict or expand the requestor’s capabilities within that right. For example, if a requestor has the general right to update indexes, the API key can limit the requestor access to only certain indexes.
Or, the API key can scope read-only access that allows a requestor to access only a small number of records.
You can use scope for further security by filtering out certain IP addresses. You can also set a time of validity, perhaps one request per day, or over a small daily number of requests over a period of 30 days.
Finally, an API key can provide filter-based limitations. For example, an API key can allow a user to update only “clothing” or “food” items. Or it can restrict a read-only requestor to perform pre-defined searches or filters.
A good example of the last point on restrictive API usage is where you grant read-only access, but restrict it with a filter that omits sensitive data. This adds additional security, allowing the requestor to see data designed only for public viewing.
But security requires more discussion.
Securing the API Key
In terms of security, an API key only goes so far. Essentially, if a key is stolen or leaked, there’s no more security.
A Stolen or Leaked API Key
There are many ways someone can get an API key. Hackers can intercept the request, steal the key, and then change the request into something far more damaging.
Or, as is more often the case, a developer may accidentally reveal the API key by sending it over the internet for anyone to easily find it. Or accidentally push it to a Git repo. Or write it on a napkin and leave it on the restaurant table.
Security Safeguards
Some security safeguards rely on additional security checks. Some of these methods require the requestor to do extra work, which undermines an API’s popularity. It’s worth keeping in mind API 101:
Ease of use is paramount to API usage, so you want to minimize all friction.
Here are some security safeguards that require no extra overhead or burden on the user of the API:
Creating rate limits, which controls the number of times the API can be called.
Creating other limits or application restrictions to minimize attacks.
Using attack-detection methods to signal unexpected behavior, referrers, or known attack behavior.
Rejecting requests that are out of the norm or damaging to privacy or the data.
And as mentioned above, removing access to non-sensitive data.
Manually create or automate the generation of new API keys regularly.
Technical note: Many of these safeguards can be added in the header as parameters in the API request.
Here are the most popular API security techniques that require developers to do more than just supply an API key:
Using a special kind of API key called a Secured API Key.
Logging in and using user ids and passwords.
Using authentication tokens (e.g., JWT tokens) for authentication and authorization.
Encrypting. For this to work, the user must have the same encryption software that the API server has. The encryption software converts the API key to unreadable data, which only the API server can understand.
The Secured API Key: Providing Server-Based Security With a Temporary API Key
A Secured API Key contains additional security safeguards over the standard API key: (a) it’s ephemeral (created on-the-fly and temporary); as such, it cannot be seen on a dashboard to be modified or managed in any way.
More importantly, (b) it contains the user’s id – thus, only one user can use the key.
Normally, API keys are generated once, for any user, and remain the same for life. However, there are two drawbacks with permanent keys:
Once someone steals the key, they will be able to use it until the theft is discovered and the key removed.
If you need 10,000s of users to have unique keys, you’ll need to create and maintain all of them. And while you can automate the generation of new API keys, you’ll almost always need to manually changes the code.
Most production-level applications need something more secure and easier to manage – without any additional work.
How it works: A Secured API Key leverages the session and/or user id by including that information as part of the key generation. Essentially, the key is generated on-the-fly by combining the user identifier with the scope of the key (e.g., timeout limits, security filters).
Once the key is generated, the requestor must always send the generated API key and its user id and scope. The API server will then re-generate the key using the user id and scope, then compare it to the key the user sent. If they differ, then it’s obviously a hack.
This double-check logic is only one step towards better security. The next step is asking the API user to log in.
Logging in – Creating API Keys With User IDs, Passwords, JWT tokens, OAuth, and OpenID
The last security method we’ll mention here involves requiring the API user to log in.
In this scenario, if the logon is successful, the API server issues a unique, unreadable token that the API user must use while they remain logged in. Additionally, the token includes the user credentials, making it difficult for anyone other than the user to send the token.
Thus, we improve upon the temporary Secured API Key method in two important ways:
JWT requires a logon.
JWT generates a token whose value contains an encrypted version of the user’s logon credentials. Those user credentials enable the API server to authenticate the user with every successive API request.
Learn more about the JWT token and how it differs from an API key.
Designing and Implementing the Best API – Tracking Usage
We’ve discussed the purposes of the API key, what it looks like, how it operates, and can and cannot be done with an API key.
We’ve also gone into some detail about security. We’ll finish on another aspect: that of tracking API usage and improving the API.
An API relies on user experience to improve its design and functionality. A company that wants to offer the absolute best API in the growing competitive API market, must know how its customers use their APIs.
By logging every request – which requests, the number of requests, the success and failures of each request, the API provider adds reporting, debugging, and analysis to the API’s design and implementation.