What is an API key?

The Postman Team

June 27, 2023· 7 mins

An API key is a unique string of randomly generated characters that is used to authenticate clients and grant access to an API.

An API key is issued by an API provider and given to a registered API consumer, who includes it with each request. The API server then checks the API key to validate the consumer’s identity before returning the requested data. API keys are not as effective as other forms of API authentication, such as OAuth and JWT, but they still play an important role in helping API producers monitor usage while keeping sensitive data secure.

Here, we’ll explain how to request and use an API key—and review the different types of API keys you might encounter. We’ll also discuss the limitations and use cases for API keys before exploring some best practices for responsible API key management.

How do you use an API key?

Every organization will have specific instructions for using its API keys, so you should consult their documentation before getting started. Nevertheless, the process for requesting and using an API key typically follows these three steps:

Step 1: Create an account

In order to use an API key, you must first create a developer account with the organization that produces the API. You’ll typically be asked to provide your email address, as well as information about your project. Some API keys are free, while others are available through paid plans that offer more generous usage limits. Be sure to review the terms of use and pricing structure before you complete the registration process.

Step 2: Copy your API key and keep it safe

Once you’ve created your account, the API producer will provide your key. An API key is often displayed on the browser just once, so be sure you copy it correctly and keep it someplace safe. Most API keys are stored in the producer’s database as hashed values, which means the producer won’t be able to provide it again if you lose it.

We’ll review some best practices for safely storing your API key later in this article.

Step 3: Include your API key in your request

API keys should be included with every request—typically in the query string, as a request header, or as a cookie. Producers will provide specific instructions for using an API key, so consult the documentation to get started quickly.

What are the different types of API keys?

There are two main types of API keys, and they each play a distinct role in helping producers manage access and API security. They are:

• Public API keys: Public API keys provide access to non-sensitive data, as well as functionality that doesn’t require authentication. They can be shared openly between team members who are working with a public API, and they are typically used by API providers to track usage and enforce rate limiting.
• Private API keys: Private API keys are used to access or modify sensitive data, and they should be kept confidential.

Sometimes, public API keys and private API keys are used together as pairs. In this scenario, the client uses the private API key to generate a digital signature, which is then added to the API request. The API server receives the request, retrieves the corresponding public API key, and verifies the digital signature. API key pairs provide an extra layer of security by preventing repudiation and enabling producers to trace requests back to specific users.

What are some of the most common use cases for API keys?

API keys are ubiquitous in modern development workflows, but they come with several drawbacks. For instance, API keys are typically registered to projects rather than individual users, which makes it difficult to enforce access control and implement multi-factor authentication. Additionally, many teams struggle with key rotation and safe storage, which leaves their API keys vulnerable to theft. This problem is compounded by the fact that some API keys do not have expiration dates. An attacker may therefore use a stolen API key for weeks or months without being detected.

While API keys are not the most secure API authentication method, they support several other use cases. For instance, they enable API producers to:

• Collaborate with consumers: API keys prevent anonymous traffic, which gives producers better insight into how consumers are using their API. This supports collaboration between consumers and producers, as an API producer can easily review a consumer’s activity and help them debug any issues they encounter.
• Limit the number of calls that are made to an API: API keys play a crucial role in rate limiting, which is the practice of controlling the number of requests made to an API by a specific client in a certain period of time. Rate limiting helps prevent resource exhaustion and protects the API from security threats.
• Monitor usage and surface trends: Because API keys enable producers to trace each request back to a specific client, they can be used to surface trends that may guide business decisions. For instance, API keys can provide insight into which organizations use specific endpoints most frequently, or which geographic location originates the most traffic.

What are some best practices for using API keys?

APIs are the building blocks of modern applications, which makes them appealing targets for security attacks. API key security is a shared responsibility between API consumers and producers, who should follow industry-standard best practices for API key management and use.

It’s important for API producers to:

• Leverage additional authentication mechanisms: As discussed above, API keys have several drawbacks that limit their effectiveness when they’re used alone. It’s therefore important for API producers to implement other authentication mechanisms alongside API keys, such as OAuth or JWT, for an additional layer of security.
• Store API keys as hashed values: Producers should avoid storing their consumers’ API keys as raw values in a database. Instead, they should store keys as hashed values, which will enable them to authenticate requests without leaving consumer keys vulnerable to theft.
• Monitor API key usage: API keys can provide important insight into how an API is being used. Producers should therefore implement monitoring and logging solutions to surface trends and detect suspicious activity.
• Scope consumers’ API keys: Rather than giving consumers access to all of an API’s data and services, producers should assign scopes to API keys. This will ensure that consumers can access the endpoints they need—without unnecessarily exposing the ones they don’t.
• Implement rate limiting: Rate limits restrict the number of calls that a certain client can make to an API in a given period of time. They help defend against Denial of Service (DoS) attacks, in which an attacker floods an API with traffic in order to exhaust its resources and take it offline.
• Provide clear, up-to-date documentation: It’s important to give consumers clear, step-by-step instructions for requesting and using an API key—especially if the API has specific usage requirements or restrictions. Clear documentation will reduce consumers’ time to first call while bolstering the organization’s reputation.

On the other side of the equation, API consumers should:

• Take precautions to prevent exposure: It’s essential for API consumers to store their API keys in configuration files or secure key management solutions, rather than hard-coding them into their application. They should also avoid pushing configuration files to a remote repository—and ensure that any publicly available screenshots do not include exposed API keys.
• Promptly deactivate compromised keys: If an API key is leaked or stolen, it should be deactivated immediately and replaced with a new one. Consumers should then carefully monitor access logs to determine whether the leaked key was used for unauthorized access.
• Rotate API keys regularly: It’s not always possible to know when an API key has been compromised. API consumers should therefore establish a process to periodically generate new keys and retire old ones in order to mitigate the risk of unauthorized use.

How can Postman help you safely manage your API keys?

The Postman API Platform includes many features that promote API key security—regardless of your API’s architecture, protocol, or use case. With Postman, you can:

• Store API keys in variables: Postman allows you to store API keys in variables, which can be scoped to a specific workspace, collection, or environment. Variables help you decouple your API keys from the rest of your code—and enable you to easily revoke or refresh your API keys as needed.
• Automatically surface exposed API keys: The Postman Token Scanner scans your public workspaces, collections, and environments for exposed authentication tokens and API keys. It includes default support for authentication credentials from over 30 service providers, and it can be customized to look for any other third-party API keys, as well.
• Receive security warnings about exposed API keys: Postman API Governance can automatically warn you of authentication-related issues, such as an API key that is exposed in a request’s URL. The warning will also include a suggested fix, so you can resolve the issue quickly.
• Easily authenticate with public APIs: Postman guides users through the authentication process for several popular public APIs, including those that require API keys. This feature streamlines development workflows and significantly reduces your time to first call.