Learn from experts and connect with global tech leaders at POST/CON 24. Register by March 26 to save 30%.

Learn more →
X

Securely using API keys in Postman

Avatar

Don’t forget to register here to attend POST/CON 24, Postman’s biggest API conference ever: April 30 to May 1, 2024 in San Francisco.

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.

#1: Do not embed your API keys directly in code

Do not embed 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.
How to Use API Keys Tip: Create a Postman environment

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.

select an 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.
curly braces to reference variables

Variables can also be referenced in script fields, such as by using pm.environment.get():scripts to reference variables

#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:

move environment to 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:

initial values are accessible to team members

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:

current values are restricted to the 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.

secret type of variable

#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.

What do you think about this topic? Tell us in a comment below.

Comment

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.

17 thoughts on “Securely using API keys in Postman

  • Avatar

    Great Stuff. Keep Posting

  • Avatar

    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?

    • Avatar

      Hi Gururaj, Please contact our support team at help@postman.com and they’ll be able to help you.🙂

  • Avatar

    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.

    • Avatar

      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.

  • Avatar

    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.

    • Avatar

      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

  • Avatar

    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?

    • Avatar

      The engineering team is looking into further optimizations to manage variables, so I’ll let them know your suggestion. Thanks for that feedback!

  • Avatar

    Even with the most recent environment variable type update, exported postman collections still show keys in plaintext. This is recipe for disaster!

  • Avatar

    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

  • Avatar

    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

  • Avatar

    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.

  • Avatar

    great workspace

  • Avatar

    What John said. Making our use of Postman pass compliance is much more difficult when all credential info is stored in plaintext.

  • Avatar

    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

  • Avatar

    This is a nice read. Really enjoyed this blog