Create and manage vault secrets

Add vault secrets to your Postman Vault and reuse them in your local instance of Postman. Then you can reference vault secrets in your HTTP collections and requests, variables, and the Collection Runner. Only you can access and use values associated with your encrypted vault secrets, and vault secrets aren't synced to the Postman cloud.

You can also use Guided Auth to add vault secrets that have authentication credentials for public APIs, and reference them in your HTTP requests.

Add sensitive data as vault secrets

After you save your vault key, you can add sensitive data, such as API keys and passwords, to your Postman Vault and reuse them in your local instance of Postman. From the HTTP request builder, you can set existing data as a vault secret. You can also set a value for a vault secret that doesn't exist in your Postman Vault, and later add the vault secret reference to your Postman Vault. Then you can use vault secrets in your local instance of Postman.

You can set vault secrets in scripts. Make sure you enable scripts to access your vault secrets. Otherwise, you'll receive an error in the Postman Console.

You can also create an integration (Enterprise teams only) that connects your Postman Vault with external vaults, such as Azure Key Vault. This enables you to link vault secrets with sensitive data stored in external vaults, and reuse it in your local instance of Postman.

Vault secrets are deleted from your Postman Vault after signing out of Postman. Existing references to vault secrets will be empty when you sign in to Postman. You can add your vault secrets to your Postman Vault after you sign in to Postman.

To add secrets to your Postman Vault, do the following:

1. Open your Postman Vault.

2. Enter the following values in an empty row:

   • Key - The name of the vault secret. Use the name to reference the secret.

   • Value - The value used when sending requests in your local instance of Postman. It's never synced to your account or shared with your team.

     To show or hide a vault secret's value, hover over the secret and select View or Hide.

   • Allowed domains - The comma-separated list of domains and subdomains you're allowed to send requests to with the vault secret. This enables you to prevent unintentional disclosure of sensitive data in your vault secret. By default, you can include vault secrets in requests to any domain and subdomain. Select the empty cell then enter your allowed domains.

     If you specify allowed domains or subdomains for a vault secret, you can only reference it at the request level.

     To allow sending requests to any subdomain of an allowed domain, use * to represent any subdomain. For example, add *.example.com to allow sending requests to any subdomain of example.com.

   

   Changes are automatically saved to your Postman Vault.

Set data as a vault secret

To set data as vault secrets from the request builder, do the following:

1. Open your Postman Vault.

2. Select the data you need. You can select data from the URL builder, the Params tab, the Authorization tab, and the Headers tab.

3. Select Set as variable.

4. Select + Set as new variable.

   

5. Enter the Name of the vault secret, confirm that the Value is correct, and select Vault as the scope.

6. Select Set Variable.

   

Set a value for a vault secret that doesn't exist

Vault secrets that aren't added to your Postman Vault are useful for trying out a value. If the value works as expected, you can add the vault secret to your Postman Vault. You can also create placeholder vault secrets to share with your API consumers. Your consumers can use the placeholder vault secret to add their own sensitive data to their Postman Vault.

You can create a vault secret reference in an HTTP request, without adding the vault secret to your Postman Vault. The value you enter for this vault secret is stored locally and only available in the request it's set in. In the variables pane under Variables used, the vault secret isn't associated with your Postman Vault.

To create a vault secret reference that isn't added to your Postman Vault, open your Postman Vault, then enter a name that doesn't exist using the following syntax: {{vault:secret-name}}. You can enter a name in the URL builder, the Params tab, the Authorization tab, and the Headers tab.

To set a value for a vault secret that isn't added to your Postman Vault, hover over it, select Enter value, then enter a value. You can also select Variables to open the variables pane, select Enter value next to a vault secret, then enter a value under Variables used.

Values for vault secrets not added to your Postman Vault are stored locally in a request until you close its tab or sign out of Postman. When you open the request again, the vault secret's value will be empty. Optionally, you can add the vault secret and its value to your Postman Vault.

Add a vault secret reference to your Postman Vault

From a Postman element, such as a request or collection, you can create a vault secret and add it to your Postman Vault. This also enables you to define a default value for a vault secret that's not added to your Postman Vault. From the element, you can add a value that's stored in your Postman Vault that only you can access and use.

Open your Postman Vault, then enter a name for a vault secret that doesn't exist in your Postman Vault using the following syntax: {{vault:secret-name}}. Hover over the reference to the vault secret, select Enter value, enter the value, then select + Add to Vault.

You can also select Variables in the workbench to open the variables pane and view the vault secrets used in your request. Select Enter value next to the vault secret, enter a value, then select +.

If you would like to store the value as a variable instead, remove the vault: prefix, then follow the instructions to add the variable to a scope.

Use vault secrets

You can reference vault secrets in your HTTP collections and requests from the URL builder, the Params tab, the Authorization tab, the Headers tab, and the Body tab. You can use the Collection Runner to manually run collections that reference vault secrets. Scheduled collection runs, monitors, the Postman CLI, and Newman don't support vault secrets.

You can access vault secrets in scripts. Make sure you enable scripts to access your vault secrets. Otherwise, you'll receive an error in the Postman Console.

If you're using the Postman web app to send requests with references to vault secrets, use the Postman Desktop Agent. You can also use the Postman Browser Agent, but you may experience the CORS limitations of browsers.

If you're referencing vault secrets linked from an external vault, you must use the Postman desktop app. Learn about external vault integrations.

Put the vault secret inside double curly braces ({{ }}) and append the prefix vault: to the vault secret's name, enabling you to reference it throughout your workspaces. For example, to reference a vault secret named "postman-api-key", use the following syntax:

{{vault:postman-api-key}}

To learn how to troubleshoot empty or unresolved vault secrets, see Troubleshoot vault secrets.

From the variables pane, you can view vault secrets that are referenced in an HTTP request and available from a Postman element. Select Variables in the workbench to open the variables pane. Review the vault secrets referenced in a request under Variables used. If the request auth is set to Inherit auth from parent, you can view vault secrets referenced in the Authorization tab of the request's parent collection or folder. Under All variables, you can view vault secrets that can be referenced and resolved in the Postman element that's open. For requests that reference a variable or vault secret, select All variables to display all vault secrets a request can access.

Vault secrets stored in your Postman Vault are masked by default when they're logged to the Postman Console. To edit whether vault secrets are masked in the Postman Console, select Settings, then turn the toggle on or off next to Mask vault secrets.

If you reference a vault secret as the initial value of a variable, such as an environment variable, the reference to the secret (for example {{vault:secret-name}}) is synced using Postman's cloud servers, and shared with anyone who has access to the workspace. The vault secret's value stored in your Postman Vault isn't synced or shared. Learn more about initial and current values.

If you're using the Postman web app with Safari as your web browser, it deletes vault secrets from your local instance of Postman after seven days of inactivity.

Use a different web browser if you want your vault secrets available for more than seven days without activity in the Postman web app.

Learn about the browser requirements for the Postman web app.

Edit vault secrets

You can edit vault secrets stored in your Postman Vault by updating them and their allowed domains, changing a vault secret's name, making vault secrets unavailable, or deleting vault secrets. You can also edit the value of vault secrets directly from requests that references it or can access it.

To edit vault secrets, open your Postman Vault. You can take the following actions:

• To filter the list of vault secrets by name, enter text in the Filter secrets box.
• To sort the list of vault secrets, select a column header. You can toggle between ascending and descending order.
• To add a new vault secret, select Add new secret in the bottom row of the table.
• To update the key or value for the vault secret, select the relevant cell.
• To delete a vault secret, hover over a secret and select Delete.
• To update the list of allowed domains, select the empty cell or list of domains.
• To make a vault secret unavailable without deleting it, clear the checkbox next to the secret. Any references to the secret will be unresolved. To make the secret available again, select the checkbox.
• To link a different secret from an external vault, select Configure vault next to the vault secret you want to update, then select Edit.

Changes are automatically saved to your Postman Vault.

You can also edit the value of a vault secret from the variables pane or the request builder. Select Variables in the workbench to open the variables pane. You can edit vault secrets referenced in an HTTP request under Variables used and vault secrets available from a Postman element under All variables. In the variables pane, delete the existing value next to a vault secret, then enter a new value. You can also hover over the reference to the vault secret in the request builder, delete the existing value, then enter a new value.