If you work with APIs, then you already know there’s many ways to prove your identity and gain access to an API, such as API keys. To help you use API keys as effectively as possible, let’s walk through some common pitfalls we see come up, and learn how to handle sensitive data in Postman.
I’m going to reference the Postman tutorial called Securely Using API Keys. If you want to join along in Postman with more detailed explanations, import the full tutorial here and follow the step-by-step documentation.
Okay, let’s look at three ways to securely work with API keys.
#1: Do not embed your API keys directly in code
Instead of hard-coding your API keys, you can store them as environment variables in Postman. In the same way you use variables for parameterized data, you can also use variables to decouple your secrets from the rest of your code. Storing your API key as an environment variable allows you to revoke, or refresh, the value in a single spot. (If environment variables aren’t ideal for your use case, you can also choose another type of variable.)
Let’s follow an example in which I use an API key stored as an environment variable.
Create an environment and add an environment variable called
api_key:Environment variables can be used in text fields with double curly braces, as you can see here with the Authorization tab:Environment variables can also be used in script fields using
#2: Do not share your API keys with your team
If you’re sharing an environment with your team, keep your tokens private by only updating the current value. This also ensures that you don’t override the team’s value.
For global, collection, and environment variables, you can distinguish between an initial and current value. The current value is local to your session within your Postman app. If you log out of Postman, those values will disappear. The current value is never synced to your account or shared with your team—unless you choose to persist it—which keeps it more secure.
Let’s walk through an example in which I share an environment with my team without sharing my personal API key.
Make sure “Automatically persist variable values” is toggled OFF in your general settings, so that you do not persist the current value of variables to the initial value:
Share the environment with your team by sharing it in a team workspace:
Initial values are accessible to your team in the workspace. For example, if you want to share information like a base URL of
https://api.getpostman.com for your API, those initial values will be accessible to the team. If someone with an environment editor role updates that initial value to v2 of the API like
https://api.getpostman.com/v2, the updated initial value is shared with the team:
Current values are restricted to your session within your Postman app. If you log out and log back into Postman, those values will be gone. The current value is never synced to your account or shared with your team—unless you choose to persist it. When you’re working with a team, you can keep your private information as a current value so your team doesn’t have access to it. Current values are restricted to your session:
#3: Do not leak your API keys publicly
If you’re sharing Postman-generated documentation with your team, or especially publicly, make sure you don’t accidentally leak secrets.
Let’s walk through an example in which I share my API documentation publicly without leaking secrets.
Use placeholder text for your API key’s value. Postman relies on string substitution to render environment values in the documentation. Display a dummy token or placeholder text—like
your-nasa-key seen in the next image—to indicate what value to use. (Note: If you leave the value blank, Postman will display no information in the rendered web documentation.)
When you’re ready to publish the collection and environment, go ahead and preview the documentation to scan for secrets. Postman will warn you about anything that appears to be a sensitive token, so you can make any updates before publishing the documentation:
Three takeaways to keep your secrets safe
To sum it all up, when you’re using API keys, keep your secrets safe with Postman by following these three tips:
- Store API keys in environment variables
- Use initial and current values
- Use placeholders to show users what info is required
For more on API keys and security, see our “How We’re Protecting Your Postman API Keys in GitHub” blog post. You can also check out Google’s best practices for securely using API keys in Google Cloud Platform (GCP) applications.