What is an API key?

An API key is a type of password that helps control access to an API. The key secures the API from improper use but also enables the API server to discern individual clients, to track API activity, and to manage and limit how the API and its resources are used.

API keys are typically a string of cryptographically generated alphanumeric characters (numbers, letters, and symbols). They’re also language agnostic which means they can be used with different types of API code: REST APIs, SOAP APIs, and so on.

Each unique API key is linked to a user account and represents an identifier for the application, the project, or the user attempting to connect to the API via an API request.

Developers use API keys to control who uses an API and how they use it. But why is that necessary?

In short, it’s a security issue. Because endpoints are public to everyone on the internet, there’s obviously a risk associated with anyone being able to make requests to your API server.

More specifically, unsecured endpoints expose you to attacks in which a malevolent actor uses an automation to take down your API server, or make you rack up a huge bill with AWS (or Google Cloud, or whoever you use to host your application). Similarly, given the rapid spike in internet of things (IoT) usage, it might become necessary to restrict the systems and applications that your API connects with for a range of security reasons.

API keys are not just for protecting your API from malicious activity — you may want to closely control who is able to access your API and what they do with it. The API key’s authorization and authentication capabilities mean that it can distinguish between users with certain privileges — paying customers, for example — and limit API use accordingly.

The solution to both API security and access challenges is an API key that, on top of performing user authentication and authorization, enables you to control what functionality or data the API exposes. For example, you could decide to restrict API usage to read-only capabilities (i.e., prevent it from writing data).

APIs serve to let different software modules communicate with each other — a process which typically entails a transfer of data or functionality. The Google Maps platform, for example, uses API keys to enable requests for map data from other applications.

With that in mind, every API key is associated with a particular API client, and essentially controls the way that communication with that client takes place.

Common use cases for API keys include:

• Limiting API calls: API keys can limit API access to another API’s services. For example, when an API server receives a call, the API key attached to that call can control the extent of the services available, or restrict services to calls that originate from certain countries. Similarly, API keys may impose limits on the number of calls an API can make or on the time period in which it has access.

• Monitor usage: In addition to controlling access, API keys can help developers monitor the way their API is being used or identify application traffic. For example, specific API keys may be issued to certain types of users, and then serve as identifiers when those particular users access the API.

• Troubleshooting: Certain APIs may create technical problems when they interact with other APIs. In these instances, the API key associated with the incident can serve to help developers detect the abnormalities, and then match those incidents with the relevant API providers as a way to kick off the troubleshooting process.

What can’t API keys do?

API keys are useful for limiting and controlling API access via user authorization but as security measures, they’re not as reliable as authentication tokens, such as OAuth tokens. Similarly, since API keys only identify projects, they can’t be used to identify users of an API or the creators behind a particular project.

It is possible to combine API keys with tokens as a way of strengthening API security. Authentication tokens differ from API keys because they contain more comprehensive identification and authentication data that can not only identify individual users but control the scope of their access to the API.

While API keys should be part of the discussion around user authorization, API security and authentication are specialized domains that we won’t get into here.

How GitHub lets you control what an API key can access

Most APIs require users to obtain API keys in order to start making requests and accessing data and functionality. Obtaining a specific API key typically involves the following steps:

• Sign up for a developer account with the API provider. Account sign-up may be free to all users or require a payment. You will need to submit certain information, such as your email address.

• Register your project with the API provider, along with any other necessary information.

• If the sign-up and registration process is successful, the API provider will send your API key which will comprise a string of randomly generated alphanumeric characters.

• In some cases, the API provider may send two API keys, one being a public key that can be shared with other project members, and a private key that should be kept secret and that enables access to your developer account and user data.

You can include API keys in your API requests in several ways:

• Pass it as a parameter or query string within the URL. For example: https://api.example.com/data?key=12345

• Include it in the Authorization field of the request header as a key/value pair.

Let’s assume you want to access the Contentful API.

We require your API calls to contain a key. The API requires that your requests contain the access_token parameter with your API key as the value.

To obtain this, you need to log in to your account and navigate to the API Keys section under Settings. This will take you to the Content delivery / preview tokens section, as seen below.

Then, click Add API key to display the Access tokens form.

In the above image, the key for this instance has been generated in the ‘access token’ field. You can also specify the key’s name, and add a description to document its use.

Additionally, note the Space ID, which restricts what the key provides access to. This differs depending on the service, and will be outlined in the API documentation.

Keep your API's data safe and secure, and protect your API keys, with the following best practices:

• User authorization: Since they are not a verifiable means of identifying individual API users, don’t use API keys alone as a means of authentication. Combine API key use with another type of security measure, such as a user authentication token.

• API code: Store your API keys in secret managers rather than in your API code as you develop. It’s easy to forget to remove your API keys from the surrounding code before you share your API.

• Safe storage: Don't forget the role that users play in keeping API keys secure. Suggest that users treat their project API keys like passwords which means storing them responsibly and not sharing them with unauthorized users.

• Deletion and expiry: When API keys fall out of use, remember to delete them to minimize any potential security risk. It might be a good idea to add an expiry date to keys for an added level of protection, and rotate new keys in for users that need to continue to use your API.

• Limited exposure: Ensure that a single API key doesn’t expose the functionality of the entire API. Restrict use to certain hosts or apps so that if a specific API key is compromised, you can limit the potential security risk.

Now that you have your API key, you’re free to make API calls however you see fit, and use any tool that you want. You’re also ready to use the Contentful SDK in your language of choice.

Remember: with Contentful, APIs work everywhere. They don’t just power websites but every tech that we use, which includes your iOS/Android apps, and probably your smart coffee machine, too.

Up next: What is an API call?