Stoplight Studio makes it easy to design your API visually with OpenAPI and helps with API authorization best practices. Try it for free today.

Stoplight Studio

“How am I going to keep this secure?” is a crucial question when building any piece of software. This question is especially critical for APIs, which provide programmatic access to important systems. Authentication shouldn’t be an afterthought but rather built into the very fabric of protecting your API.

Simply put, authentication is the act of verifying that you are who you claim to be. Think of it as needing a key to open a locked house. The key confirms who you are and grants you access to what’s inside.

There are many methods of API authentication, such as basic auth (username and password) and OAuth (a standard for accessing user permissions without a password). In this post, we'll cover an old favorite, the API Key and discuss how to authenticate APIs.

Many early APIs used API Keys, which were often an improvement on passing other credentials in API code. There are drawbacks to API Keys, but it’s also a simple way to secure access. However, not everyone agrees on how to pass keys to an API, and how API authentication and keys work. We’ll cover that, as well as some examples. But first, why would you want—or not want—to choose API authentication? Let's discuss by looking at alternative authentication methods and API authentication best practices.

Pros and Cons of API Key Authentication and How to Use Them

Like most topics, you’ll find varying opinions about using API key authentication over other authentication methods. It remains a popular method, though developers should be aware of the tradeoffs. Let's look at API key meanings and how to use them.

One of the clear advantages of using API key authentication is its inherent simplicity (this is under authentication best practices for sure). It’s a single authentication key that allows you to authenticate just by including the key. This simplicity also allows a user to make calls easily, with cURL, interactive docs, or even in their browser.

Another advantage comes along with its popularity. Developers are familiar with API keys. The easier and quicker it is to authenticate to your API, the more likely the developer will find success. Whether that developer is within your own company or an external partner, you want your API to be easy to use.

On the other hand, simplicity may raise security concerns. What happens if someone else comes upon an API key that is not their own? In most cases, they can use the API key with all the privileges of the rightful owner. Depending on the API, they may be able to retrieve all the data, add incorrect content, or delete everything.

One precaution that some API designers take is to use API keys for read-only data. For APIs that don’t need write permissions, this is especially useful, while limiting risk. However, this approach limits the APIs that may require more granular permissions.

However, many use cases remain that make sense for the simplicity of API keys. And there are several places where API keys may be passed during your API design.

X-API-Key and Other HTTP Header Types

The most popular API key location for modern APIs is in headers. However, that’s not enough information. It raises the question, “Where in the headers should you include the API key?” There are many methods for including API keys in an HTTP header.

Before we show the various choices, an important note: as with all API requests, use HTTPS (TLS, the successor to SSL) to ensure the data is encrypted in transit.


The most popular choice, perhaps due to its usage by AWS API Gateway, x-api-key is a custom header convention for passing your API key. For more on API gateway authentication, check this out. 

GET / HTTP/1.1
X-API-KEY:  abcdef12345

Basic Authentication

How long should an API key be? It depends. Earlier, we suggested Basic Auth as an alternative to API keys, as one of the API authentication types. They can also be used together. You can pass the API key via Basic Auth as either the username or password. Most implementations pair the API key with a blank value for the unused field (username or password).

GET / HTTP/1.1
Authorization: Basic bWFnZ2llOnN1bW1lcnM=

You will need to base64-encode the ‘username:password’ content, but most request libraries do this for you.

Bearer Authentication

Some APIs use the Authorization header to handle the API key, usually with the Bearer keyword. This method is also used for other tokens, such as those generated by OAuth.

Authorization: Bearer abcdef12345

What about non-header locations for API keys? You can find them in query strings or even the data body.

Other API Key Locations

Though the header has become the preferred location for API keys, there are non-header methods still used by many APIs. As a developer using APIs, you can look out for these methods. As an API designer, you’ll probably want to stick to the headers, as we’ll explain in each section.

Query String

The popular method for early APIs, it’s certainly easy to pass an API key through a query string in a URL. However, this method can risk API key exposure since, despite encryption, the parameters can be stored in web server logs.

curl -X GET ""

If you use the query string method, you’ll want to make sure that there’s a low risk of the API key being shared.

Request Body Parameter

Another method we’ve seen, especially in older APIs, is to pass an API key in the POST body as JSON:

curl -X POST
	`’ \
	-H ‘content-type: application/json’ \
	-d ‘ {
		“api_key”: abcdef12345”

The most significant drawback to this method is that authentication is mixed in with other data. It also encourages poor REST practices, as simple reads from the API would need to be sent a POST request instead of GET.

JavaScript API

Finally, you may see API keys used with frontend JavaScript APIs, which provide in-browser access to API functionality. In these cases, the API key is passed one of two ways. Either the key is passed with the call to the script or in the JavaScript itself.

For example, Google Maps passes the key in the query string to the JavaScript:

 <script async defer src="" type="text/javascript"></script>

Keen Dataviz, on the other hand, passes the API in a constructor:

const client = new KeenAnalysis({
  projectId: 'YOUR_PROJECT_ID',
  readKey: 'YOUR_READ_KEY'

In both cases, the companies take additional steps to secure the API calls, since the API keys are essentially public (easily discoverable if you view source). Google Maps allows developers to restrict its usage on certain websites. Keen has separate read and write API keys.

🔗 API Key Authentication using OpenAPI

In addition to human-readable API documentation, an OpenAPI definition is a must when designing APIs. You can describe your entire API in a machine-readable file (YAML or JSON). The format is meant to cover the many ways developers create RESTful APIs and provides API keys explained, so it is flexible enough for the various API Key methods we discussed.

For example, here is the security section of Stripe’s OpenAPI document, showing the two header approaches supported for its API keys:

      description: 'Basic HTTP authentication. Allowed headers-- Authorization: Basic
        <api_key> | Authorization: Basic <base64 hash of `api_key:`>'
      scheme: basic
      type: http
      bearerFormat: auth-scheme
      description: 'Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
      scheme: bearer
      type: http

Ultimately, having a machine-readable API specification allows you to test the implementation against the specification throughout your API development lifecycle without extensive effort.

Stoplight Studio makes it easy to design your API visually—including security definitions around any authentication—with OpenAPI. We hope you enjoyed these API authentication and authorization tips!

For more on API authentication, check out this blog.



Peek-a-Boo (1)

Subscribe for the latest in API Design

By submitting this you will be receiving our latest updates on post.

Take a Listen to API Intersection

The podcast on the intersection between API design & digital transformation

Related Posts