A common question when working with APIs is “What is an API key?”. Application programming interfaces (APIs) allow software programs to interact, share data, and integrate their functionalities.
APIs facilitate conversations between otherwise disconnected software and are the technology behind many powerful integrations you use daily. Unlike a face-to-face conversation, however, it’s harder for an API to verify whether the app it's talking to is who it claims to be. API keys play a significant role here, and understanding their importance in an API context is essential.
What is an API Key?
An API key is an identifier assigned to an API client, used to authenticate an application calling the API. It is typically a unique alphanumeric string included in the API call, which the API receives and validates. Many APIs use keys to keep track of usage and identify invalid or malicious requests.
In general, API keys serve two primary functions in an API request:
- Project authentication: The API key identifies the application requesting the API receiving the request. Each project has a unique key to distinguish it from other projects.
- Project authorization: The API key tells the API whether the requesting application has permission to use the API and which of the API’s services it may access. Even if an application can access an API, it might only be authorized to use a limited set of the API’s services.
Based on the API key provided in a request, the API checks the key with its client database, then either accepts or denies the request. If the request is rec, the API grants the client access to its data and functionality based on the client’s access rights, which are also associated with the API key.
Additionally, API owners use API keys to monitor API activity, including the types of requests and volume of requests from individual clients. Since each request has an associated key, the API owners can filter by key and view all requests from a particular client.
This monitoring ability is critical when protecting the API from harmful traffic. Hackers frequently target APIs through various methods, such as faking credentials to inject harmful code or overwhelming the API server with requests. With keys, an API can eliminate anonymous bot traffic or block requests from a particular user if needed.
It’s important to note that API keys identify project and application requests, not individual users. An API key tells the API which project the request came from, but it cannot identify specific users with access to the project. This is a significant security limitation that we’ll discuss later on.
The following video helps illuminate the subject of API keys and how you can use them.
How to Use an API Key
APIs usually require developers to acquire a key before making requests. The process should be documented on the API developer’s website and tell you everything you need to get started.
In most cases, you’ll need to sign up for a developer account with an email and other information. Then, you’ll be asked to register your project and enter any project information the API owners should know.
You should receive at least one API key, a unique string of randomly generated characters associated with your project. It will look something like this:
You may receive two keys, one labeled as your “public key” and the other as your “private key.” A public key can be shared with collaborators and is more limited in access to the API’s data and functions. Your private key should not be shared with anyone — it’s a more definitive identifier of your project and gives access to your developer account, plus all of your data.
As for including your API key in requests, refer to the API’s documentation for where to place your key — typically, it’s in the request header:
Or written in a query string following the request method:
Are API keys secure?
Web APIs are a common target of cyberattacks because they transfer sensitive data between applications — including login credentials, personal information, and financial transactions — over the internet. To combat this, web APIs need to be very secure.
API keys can identify a project to an API and specify which resources a project may access. However, experts do not consider API keys to be secure enough on their own. This is for a few reasons:
- API keys can’t authenticate the individual user making the request, only the project or application sending the request.
- API keys are like passwords — only effective if the owner stores them securely. If a key falls into the wrong hands, it can easily be exploited.
- Since API keys rarely expire, a hacker can use the key indefinitely unless the key’s owner regenerates or deactivates the key.
For these reasons, popular APIs today also employ user authentication and authorization. User authentication checks that the individual making the request (not just the application) is who they say they are. User authorization verifies that this person is allowed to complete their request.
User authentication and authorization are accomplished with authentication tokens, which are more secure than API keys. The OAuth protocol is today’s standard for user authentication and authorization, allowing users to verify their identity without providing a password. This is the same technology behind single sign-on, in which users can log into one application (like LinkedIn) through another application (like Google).
OAuth is a more complex process that deserves a dedicated article, so here’s an explainer that goes in-depth on how OAuth works.
How to Store API Keys Securely
Despite their drawbacks, API keys are still popular and valuable for identifying calling projects. There’s a good chance you’ll need to keep track of one or several when working with an API.
API keys work a lot like passwords and should be stored and protected. Here are some basic steps you can take to limit the risk of a stolen key:
- Don’t write down your key in a public place — like on a sticky note or in a file on a public computer. You can safely access your key inside your developer account.
- Be careful not to accidentally expose your key when documenting your project, such as with screenshots, uploading to a public repository, or in a URL.
- Don’t write your API key directly into your program, as anyone with access to your source files can see your key.
- Before sharing your API key, regenerate it and label it as the newest shared key.
- Don’t share API keys through email.
- Always use HTTPS/SSL for your API requests — some APIs won’t field your request if you’re not using it.
- Assign a unique API key to each project and label them accordingly. If you discover a compromised key, you can regenerate or deactivate it without affecting your other projects.
API Key Examples
Here are some examples of popular APIs and how they implement API keys for security to drive this lesson home.
Google Maps API Key
The Google Maps Platform uses API keys to secure its requests for map data. After setting up a developer account with Google, you can easily create a Google Maps API key in your credentials area.
Google also encourages users to restrict their API keys to accepted domains and allows you to do this in the credentials area. Additionally, the Google Maps API only accepts requests secured with HTTPS.
Google provides the following example of what an API key looks like in a request:
Want to put interactive Google maps on your site or app? Check out our guide to getting started with Google Maps APIs.
What We Like:
The simplicity of Google’s API and related keys makes them an excellent choice for starting with using APIs and API keys.
Stripe API Key
To authenticate requests to its API, payment processing service Stripe provides API keys for each developer account. Specifically, it issues two types of API keys: “publishable,” which is your public key that associates your account with Stripe, and “secret,” your confidential private key that lets you make any request to Stripe.
Best For Testing:
Stripe issues two pairs of publishable and secret keys, one for your live application and one for API testing. This gives your four keys total. Test API keys include the substring _test_.
Stripe also lets users generate keys with more significant restrictions if you implement the API in a microservice.
When to Use an API Key
API Keys can be very useful and offer more control over how your application software can be used, but knowing when to use them can be a little confusing. Before wrapping up this post, check out the list below, which can help identify when you might want to use an API Key for your project.
Block Anonymous Traffic: Anonymous traffic may indicate potentially malicious activity or traffic. API keys can identify application traffic and help debug issues or analyze usage.
Control API Calls: Controlling calls to your API helps limit consumption, traffic, and usage to ensure legitimate traffic accesses the API.
Identify API's Traffic: Identifying usage patterns help spot malicious activity and issues within the API.
Filter Logs: Activity on the API server can be logged and filtered by the specific API key.
API Keys also have significant limitations that you should consider. Below is a list of things to keep in mind.
Secure Authorization: API keys should not be used for secure authorization because they are not as secure as authentication tokens.
Identifying Project Owners or Creators: API keys can only identify the project making a call, not who created or owns the project.
Identifying The Users: API keys are used to identify projects, not those that access a project.
Help secure your requests with API keys.
Though API keys are not the only (or even the best) API security measure, they’re still helpful for API vendors and necessary for authenticating API integrations.
As API integrations develop and spread among new applications and smart devices, one thing won’t change: There will always be people looking to steal and exploit personal data. That’s why any reputable API transmits sensitive information will include API keys (and more) in its security arsenal.