“What is an API key?” is a frequently asked question when working with APIs. APIs enable software programs to interact with one another, share data, and integrate their functions. APIs enable communication between otherwise disconnected software and are the technology behind many of the powerful integrations you use every day.
However, unlike a face-to-face conversation, it is more difficult for an API to verify whether the app it is communicating with is who it claims to be. APIs require methods of identifying their clients before allowing them to pass because they frequently expose private and sensitive information. Otherwise, it’s a significant security risk.
API keys are one such security measure; they function as an ID card for the client making an API request, assisting APIs in assigning appropriate access permissions and tracking how their data is used.
If you work with APIs or marketing integrations, you should understand what API keys are, how they fit into API security, and why they should not be your only layer of protection. Allow us to explain.
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.
The API checks the API key provided in a request against its client database, then accepts or denies the request. If the request is accepted, the API grants the client access to its data and functionality based on the access rights associated with the API key.
API owners also use API keys to monitor API activity, such as the types and volume of requests from individual clients. Because each request is associated with a key, API owners can filter by key and view all requests from a specific client.
This monitoring capability is essential for protecting the API from malicious traffic. APIs are frequently targeted by hackers using a variety of methods, such as faking credentials to inject malicious code or flooding the API server with requests. An API can use keys to eliminate anonymous bot traffic or block requests from a specific user if necessary.
It is important to note that API keys are used to identify project and application requests rather than individual users. An API key tells the API from which project the request originated, but it cannot identify specific users with project access. This is an important security limitation that we’ll go over later.
How to Make Use of an API Key
Before making requests, APIs typically require developers to obtain a key. The process should be documented on the API developer’s website and should include all of the information you need to get started.
In most cases, you’ll need to create a developer account by providing an email address and other information. Then you’ll be prompted to register your project and provide any project information that the API owners should be aware of.
You should receive at least one API key, which is a random string of characters associated with your project. It will resemble the following:
You may be given two keys, one labeled “public key” and the other “private key.” A public key is more limited in its access to the API’s data and functions and can be shared with collaborators. Your private key should not be shared with anyone; it serves as a more permanent identifier for your project and grants access to your developer account as well as all of your data.
Refer to the API documentation for where to include your API key in requests — typically, it’s in the request header:
Or written in a query string following the request method:
Are API keys protected?
Web APIs are a popular target for cyberattacks because they transmit sensitive data between applications over the internet, such as login credentials, personal information, and financial transactions. To combat this, web APIs must be extremely secure.
API keys can be used to identify a project in relation to an API and to specify which resources a project may access. However, experts believe that API keys are insufficiently secure on their own. This is due to several factors:
- 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.
Popular APIs today use user authentication and authorization for these reasons. User authentication ensures that the person making the request (rather than the application) is who they claim to be. User authorization confirms that this individual is authorized to complete their request.
Authentication tokens, which are more secure than API keys, are used for user authentication and authorization. The OAuth protocol is today’s standard for user authentication and authorization, allowing users to authenticate themselves without providing a password. This is the same technology as single sign-on, which allows users to log into one application (such as LinkedIn) through another (like Google).
OAuth is a more complex process that deserves its own article, so here’s an explanation of 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 secures map data requests with API keys. After creating a Google developer account, you can easily generate a Google Maps API key in your credentials area.
Google also encourages users to limit their API keys to accepted domains, which you can do in the credentials section. Furthermore, the Google Maps API only accepts HTTPS-secured requests.
Google provides the following example of an API key in a request.
Do you want to include interactive Google maps on your website or app? Check out our beginner’s guide to Google Maps APIs.
What We Dig:
Google’s API and related keys are an excellent choice for getting started with APIs and API keys due to their simplicity.
API Key for Stripe
Stripe, a payment processing service, provides API keys for each developer account in order to authenticate requests to its API. It generates two types of API keys: “publishable,” which is your public key that connects your account to Stripe, and “secret,” which is your confidential private key that allows you to make any request to Stripe.
Ideal for testing:
Stripe generates two sets of publishable and secret keys, one for your live application and the other for API testing. This brings your total to four keys. The substring _test_ appears in test API keys.
Stripe also allows users to generate keys with more stringent restrictions if the API is implemented as a microservice.
When Should You Use an API Key?
API Keys can be very useful and give you more control over how your application software is used, but knowing when to use them can be difficult. Before we wrap up this post, take a look at the list below to see when you might want to use an API Key for your project.
Anonymous traffic should be blocked because it may indicate potentially malicious activity or traffic. API keys can be used to identify application traffic and assist in debugging and usage analysis.
Control API Calls: Limiting API calls helps limit consumption, traffic, and usage to ensure only legitimate traffic accesses the API.
Identify API Traffic: Recognizing usage patterns aids in the detection of malicious activity and issues within the API.
Filter Logs: API server activity can be logged and filtered based on the API key.
API Keys have significant limitations that you should be aware of. Here is a list of things to remember.
API keys should not be used for secure authorization because they are less secure than authentication tokens.
Identifying Project Creators or Owners: API keys can only identify the project making the call, not who created or owns the project.
Identifying Users: API keys are used to identify projects, not the users who access them.
API keys can help secure your requests.
Though API keys are not the only (or even the best) API security measure, they are useful for API vendors and required for API integration authentication.
One thing will remain constant as API integrations spread across new applications and smart devices: there will always be people looking to steal and exploit personal data. As a result, any reputable API that transmits sensitive information will include API keys (and other security measures) in its arsenal.