Securely using API keys in Postman
Last updated on March 20, 2023.
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.
Let’s look at three ways to securely work with API keys. Build your own example by following this step-by-step tutorial, or fork the example collection and environment in this workspace to follow along.
- Fork the example collection: Securely using API keys in Postman
- Fork the example environment: Securely using API keys in Postman
#1: Do not embed your API keys directly in code
Instead of hard-coding your API keys, you can store them as 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 a variable allows you to revoke, or refresh, the value in a single spot. There are different variable scopes to suit different use cases.
Let’s follow an example to store an API key as an environment variable. Using Postman environments allows you to decouple specific variables so they can be used alongside different collections and shared separately with other team members and collaborators.
Create an environment and add an environment variable called api_key
, and Save your changes.
Postman displays the active environment in the environment selector, located in the top right of the workbench. You can also access all environments from Environments in the sidebar and select the set active icon next to an environment to make it the active environment.
Variables can be referenced in text fields with double curly braces, as you can see here with the Authorization tab. Hover over the variable name to inspect the variable’s value and scope.
Variables can also be referenced in script fields, such as by using pm.environment.get()
:
#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.
Share the environment with your team by moving it to 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:
You can also define environment variables by Type. Variables are automatically assigned the default type when created, which is shown as plain text and has no extra properties. Users with editor role can change sensitive variables to secret type, which masks the initial and current values for all workspace members. Secret type can be used to prevent unintentional disclosure of sensitive data, including API secrets, passwords, tokens, and keys.
#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 publish my API documentation publicly without leaking secrets.
Use placeholder text for your API key’s value. Postman relies on string substitution to render the initial values of 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 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.
Great Stuff. Keep Posting
Hi ,
I am using a proxy in POSTMAN which listens on port 8500. I have disabled the “ssl verification” but when I connect to my application, it still fails with error message
Got error: Post “https://:8443/api/v2/login”: x509: certificate signed by unknown authority
What am I missing here?
Hi Gururaj, Please contact our support team at help@postman.com and they’ll be able to help you.🙂
Is there a way to hide and lock the credentials in postman? Right now they are plain text and anyone who would be shortly using my computer will be able to simply copy the credentials.
If you’re using a shared workspace, like a Team or Public workspace, keep your credentials private by using the CURRENT VALUE (instead of INITIAL VALUE). If you’re using a shared computer, log out of Postman.
What @bendroid said. I work mainly using pair programming with a buddy, and then when I use Postman, my api keys are exposed during the pair programming sessions via video stream.
Oh I see, and I have that problem too. It looks like there’s an open feature request that could solve the issue. Please add your use case or upvote the relevant comments here, so the product team understands this scenario: https://github.com/postmanlabs/postman-app-support/issues/6639
Great information, really, but I think Postman is lacking here. Holding individual secrets secret should be possible to do without the cumbersome and error prone process described above. Why not just make it possible to have individual environment variables that each developer can persist without sharing them with the team that simply overrides any team variables?
The engineering team is looking into further optimizations to manage variables, so I’ll let them know your suggestion. Thanks for that feedback!
Even with the most recent environment variable type update, exported postman collections still show keys in plaintext. This is recipe for disaster!
Hi all. There is a built-in JavaScript library in Postman, called CryptoJS. It can be used to encrypt (and later, decrypt) values which are stored in your Postman application. To my knowledge (please, please someone tell me if I am mistaken!), Global variables are not synced to Postman’s servers – therefore, you can create a secret key to use to encrypt and decrypt your variables. The key would not necessarily need to be saved to your Postman workspace either. e.g.
// encrypt + store (you’d only need to do this once)
const encryptedKey = CryptoJS.AES.encrypt(‘yourApiKey’, ‘your$ecret’).toString();
pm.globals.set(‘encryptedApiKey’, encryptedKey);
// decrypt (whenever you choose to access it)
const apiKey = CryptoJS.AES.decrypt(pm.globals.get(‘encryptedApiKey’), ‘your$ecret’).toString(CryptoJS.enc.Utf8);
More information on CryptoJS can be found here: https://www.npmjs.com/package/crypto-js
More information on implementations and security can be found here: https://javascript.plainenglish.io/how-to-send-encrypted-data-with-postman-6d5a052e21f5
I want to post request without access key as access key is same every time for all requests. So let me know how i can send request without it. I want if i define it in any header then it should work for all requests & collections
I know that this post is nearly 2 years old, but storing keys in raw text env vars is still less than ideal. A built in password vault or integration to exists vaults is desperately needed.
great workspace
What John said. Making our use of Postman pass compliance is much more difficult when all credential info is stored in plaintext.
Jayce, A Variable was create on Environments, and I am using it on my script to increate the value in 1. It’s working well.
On Body I am try to use the variable’ Current Value, but only the “Initial Value” is returning. I already used Persiste ALL, but nothing happened.
How to set on body tha variable to read the Current value and NOT the Initial value?
Thanks
This is a nice read. Really enjoyed this blog
i am try to save global variable but on clicking save button it doesn’t get saved. what is the reason why save not working?
Please contact our support team at http://www.postman.com/support and they’ll be able to help you.