API keys and API tokens are often discussed as synonyms, but in practice, they are very different. Below, we’ll see how these two technologies differ and consider where they are best used.

What Is an API Key?

An API key is a simple yet powerful string of text. Each key is generated for a specific entity and serves as the key to the kingdom for that entity. Each time a call is made to the API, the key is shared, functioning similarly to an account username and password pair. Since these keys are unique, they serve as an identifier that can connect to other security layers, identification routines, and rate-limiting approaches.

In application, keys are typically connected directly to a specific device, and they do not identify who is using the key as much as what device is making the request. For this reason, it’s not uncommon for a single user to have a key for a mobile device, a key for a desktop computer, or a key for an external API, even if all of these devices are directly interfacing with the same API.

It should be noted that API keys are often treated as a standalone security layer. As we’ve discussed previously, this is an improper use of an API key and should be avoided. API keys were never meant to function as a security feature — they were meant to serve as an identification item. While identification can indeed play a role in other security systems, hinging the entirety of a security posture on simple identification is incorrect and dangerous. Instead, API keys should play a small role in a much larger system of authorization and authentication that is robust, adaptive, and routinely tested.

An example API key could look as follows.

key: a9nIbdnaoks97028Jlf.ains9NIKQMEO

What is an API Token?

An API token is somewhat more complicated. API tokens are also simple strings of code, but they typically contain more data about the user. Tokens can be device-specific, flow-specific, or specific to any number of variable states. These tokens often contain a specific structure — Header, Payload, and Signature — and are generated by an authority to control access.

API tokens can also see their function extended through various unique applications. Single-sign-on (SSO) tokens are one good example, where a single token can be given a domain of applicability and thus used across multiple APIs. These APIs agree upon a system of common issuance and acceptable authentication and authorization, forming a domain, or federation. Within this group of APIs who agree upon the common modality, the same SSO token will be accepted as valid and used to unlock continued access individually or cross-API access.

The following is an example JWT token as provided by the Auth0 documentation.

{
      "alg": "RS256",
      "typ": "JWT"
    }
    .
    {
      "iss": "https://example.auth0.com/",
      "aud": "https://api.example.com/calendar/v1/",
      "sub": "usr_123",
      "scope": "read write",
      "iat": 1458785796,
      "exp": 1458872196
    }

Similarities Between API Keys and API Tokens

Part of the confusion around API keys and API tokens arises from the fact that, at least on paper, they might seem very similar to one another. This is primarily due to their everyday use, so let’s explore what that common use might look like.

API keys are often used for identification, and in this way, they are very similar to how some tokens are used. Tokens may carry some identification functionality as part of their core use, and so to the outside user, these are very similar in practice. An API key identifies the user through a pair of identity proofs (username/password pairs, typically). In the same way, an API token may carry this information as a method for identification.

The similarities also come in the form of visual function. As keys and tokens are, in simplest form, just strings of code, an observer might look at the two and think they are interchangeable. While some API keys are more complex, the simplest API tokens can appear like the most complex of API keys.

Differences Between API Keys and API Tokens

Visual similarity aside, API keys and API tokens are, in fact, very different things. API tokens often contain more pieces, such as a header and payload, whereas API keys are typically streamlined. The two items are designed to do very different things.

API keys are meant to identify applications, and that’s pretty much it. Despite the inclination of many novice developers to use API keys as a form of authentication and authorization, API keys are only really supposed to be for identification. The confusion arises from the fact that API keys are often used as part of a more comprehensive security solution. In this use, they are often the most visible component of that security approach.

Think about a driver’s permit — the permit itself does not serve as a guarantee of the right to drive a vehicle, but rather identifies the driver as being licensed. The licensing system itself is what gives the right to drive. In the same vein, an API key might serve as the entry point for a user to be authenticated and authorized, but only in as much as it identifies the device as they enter the system, which actually performs the security mechanism.

On the other hand, Tokens tend to carry significantly more data with them. Tokens are designed to identify users, and in doing so, often carry additional information for authorization. These tokens are typically granted via a token generation flow internal to the API and typically pair not only an identification of the source — akin to an API Key — but also the level of authorization and trust placed with the user who bears the token.

It should be noted that tokens carry with them a much more complex flow than keys typically do. A key is usually granted pretty liberally — after all, the only thing a key really does is serve as a form of identity. Tokens, on the other hand, and especially in OAuth, carry a much more complicated granting and expiration process and typically have more complex interactions and limitations. Flows are defined by how they’re granted — you’ll often hear terms like “implicit flow” or “device flow” that define how these tokens are granted and used.

The prime difference between API keys and API tokens can be thought of as follows: API keys define the source of the requesting entity, whereas API tokens identify the user and their rights.

Practical Implementations

There are a few things to consider when choosing between API keys and tokens.

First and foremost, API keys are typically considered less secure than tokens. There are a few reasons that this is largely true, but perhaps the most significant is that API keys are typically less granular in their security controls. So the loss of a key could mean the exposure of the entirety of an API. While you can, in theory, issue different tokens for different devices and attempt some limited functionality based upon the passage of the API key into the header, this introduces another risk — API keys are typically embedded in requests, thereby making it much easier to capture in transit.

While the current proposed standard is indeed to pass these keys in the Authorization header, it often finds itself in other locations. This can be a problem even for developers who abstain from this pitfall. You can only control what your API does, and this is problematic with other APIs that pass this key through plaintext or body contents.

On the other hand, an API token is typically much more granular, limiting the potential security downside of a token being lost. This comes at a cost, however, with tokens being much more complicated and larger. For this reason, full-blown tokens can be difficult to handle in more limited computational environments such as the Internet of Things, although advances in bearer tokens and other implicit flows have drastically reduced this potential downside over the last few years.

It should also be noted that API keys are less standardized than tokens. A key is typically internally generated, and while API developers can create a strong security system using proprietary approaches, the fact is that there are many open source and common standards in place currently around tokens that already deliver this benefit. Adopting something like OAuth is going to lead to a more secure solution than simply building a proprietary shell around internally generated keys.

Examples of API Keys and API Tokens

To ground our definitions in some practical examples, let’s consider how API keys and API tokens are being utilized within some production software. First, you don’t have to look far to find an API key — many public APIs require the client to provide an API key when making requests to the server. These are what API products often track to conduct metering and billing.

API Key Example: OpenWeatherMap

For example, OpenWeatherMap’s OneCall API relies on API keys to denote the ID of the application making the API request. By passing in this credential within an HTTPS request, developers can request information like current weather and forecasts, historical weather data, and daily aggregations of weather information. The API key is inserted into the request as such:

https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude={part}&appid={API key}

API Token Example: Single-Page Application

For an example of how API tokens are used in practice, consider a single-page applications (SPA). Such web applications have no backend at all, but instead call the relevant APIs to populate the client with data. In this scenario, a token handler pattern is a good way to keep access and refresh tokens secure.

Conclusion

API keys have their place in modern development, but they are often used to such an extent and in such a way that they were never designed to be used for. Open standards and open-source solutions back API tokens, which are great for securing APIs and ensuring adequate authentication and authorization.

Did we miss something? Let us know in the comments below!