Create and manage vault secrets in Postman Vault

Manage vault secrets in your Postman Vault to securely store and control access to sensitive data, such as API keys and tokens. Vault secrets include a key name, value, and optional allowed domains that determine where they can be used.

You can add vault secrets to your Postman Local Vault or Postman Shared Vault, use them in requests, and update or remove them as needed. The two vault types are managed in different places and follow different access rules, so each has its own steps on this page.

Manage local vault secrets

Only you can access vault secrets in your Postman Local Vault, and they aren’t synced to the Postman Cloud. You add, edit, and delete them directly in the local vault’s table of secrets.

Add vault secrets

Add sensitive data, such as API keys and passwords, to your local vault to securely store and reuse it. Vault secrets are encrypted using Advanced Encryption Standard (AES) with a 256-bit key length.

To add a vault secret, do the following:

1. Open your local vault.

2. Enter the following values in an empty row:

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

   • Value — The sensitive data used when sending requests.

   • Allowed domains — A comma-separated list of domains and subdomains where the vault secret can be used. This helps prevent unintentional disclosure of sensitive data. By default, vault secrets can be used in requests to any domain. If you specify allowed domains, the secret can only be used at the request level for those domains.

     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.

After you add a vault secret, you can use it in your requests by setting it as the value of a secure variable. Learn more about using vault secrets in Postman.

Other options for adding vault secrets to your Postman Local Vault only include:

• Create an integration — Connect your local vault with an external vault provider, such as Azure Key Vault, to link and reuse managed secrets. Postman Vault integrations are available on Postman Enterprise plans with the Advanced Security Administration add-on. Learn more about Postman Vault integrations.
• Set existing data as a vault secret — Select data in a request and save it as a vault secret.
• Set vault secrets in scripts — Use the pm.vault.set() method to create vault secrets.

Set data as a vault secret

You can save values from a request as vault secrets in your local vault. This is useful when you receive sensitive data in a response or have existing data in your request that you want to secure as a vault secret.

To save data from a request as a vault secret, do the following:

1. Select the value you want to store, such as in the URL builder or Params tab.
2. Right-click the selected value and select Set as variable.
3. Click Set as new variable.
4. Enter a name for the vault secret, confirm the value, and select Vault as the scope.
5. Click Set Variable.

To save authorization credentials as a vault secret, do the following:

1. Click the Authorization tab.
2. Select an authorization type.
3. Enter a value in a field that holds sensitive data (such as a password or token).
4. Hover over Sensitive value, then click Set as Variable.
5. Enter a name for the vault secret.
6. Select Local Vault.

Set vault secrets in scripts

You can set vault secrets in your local vault from your scripts using the pm.vault object. Use pm.vault.set() to create or update vault secrets at runtime.

The pm.vault methods are asynchronous and return a Promise. Use the await operator to ensure the value is resolved before using it in your script.

await pm.vault.set("postman-api-key", "my-secret-value");

Edit vault secrets

You can edit vault secrets in your local vault by updating their values, names, and allowed domains. You can also update vault secret values directly from requests that reference them.

To edit vault secrets, open your local vault and use the following options:

• Filter secrets — Enter text in the Filter secrets box to find secrets by name.
• Sort secrets — Click a column header to sort the list in ascending or descending order.
• Add a secret — Click Add new secret in the bottom row of the table.
• Edit key or value — Click the key or value cell to update it.
• Edit allowed domains — Click the allowed domains cell to update the list.
• Make a secret unavailable — Clear the checkbox next to a secret to make it unavailable. References to the secret are unresolved until you select the checkbox again.
• Delete a secret — Hover over a secret and click Delete. Learn what happens to related variables and requests when you delete a vault secret.
• Update external vault link — To link a different secret from an external vault, click Configure vault, then click Edit.

Delete vault secrets

A vault secret you’ve added to your local vault is often referenced as the value of a secure variable, which you can then use in requests and scripts. Deleting a vault secret only removes the secret itself. It doesn’t remove the secure variable that references it, or that variable’s references in your requests and scripts.

To fully remove a vault secret and stop using it, delete the following:

• The vault secret from your local vault.
• The secure variable, in its global, environment, or collection scope, that references the vault secret.
• Each reference to the variable in your requests and scripts.

Manage shared vault secrets

Secrets in your workspace’s Postman Shared Vault are available to teammates through secret references, so no one has to store the secret locally or share it manually when it changes.

Shared vault secrets follow different rules from local vault secrets. Each one has an access scope that controls who on your team can use it, and only its creator and a Security Manager can read its value.

Create a shared vault secret

Anyone with Editor or Admin access to a workspace can create a shared vault secret from that workspace.

To create a secret in your shared vault, do the following:

1. Open your workspace’s shared vault, then click Secrets > Postman vault.

2. Click + Add Secret.

3. Enter the following:

   • Key — The name you use to reference the secret, such as stripe_secret_key. Key names are visible to everyone on your team, even for secrets they can’t use, so avoid including sensitive details.

   • Secret value — The sensitive data to store, such as an API key or a token.

   • Allowed domains (optional) — A comma-separated list of domains where the secret can be used, such as api.example.com, *.internal.example.com. Use * to represent any subdomain. By default a secret can be used in requests to any domain, which your shared vault shows as All domains.

   • Who can access this secret — The secret’s access scope:

     • Workspace — (Default) Members of the workspace you’re creating the secret from, called the origination workspace, can use it, and you can use it in any workspace you belong to. The origination workspace keeps its access permanently: teammates who join it later gain access, and teammates who leave it lose access. If you change the scope later, its members can still use the secret. To revoke their access, delete the secret and start over.
     • Share with user and members of origination workspace — The teammates you select can use it in any workspace they belong to, along with members of the origination workspace. Search for each teammate by name or email.
     • Entire team — Every member of your team can use it, in any workspace they belong to. You can’t narrow the scope later. To revoke access from the team, delete the secret and start over.

4. Click Save.

You’re the secret’s creator, so you can manage the secret regardless of your team role. You can use it in any workspace you belong to, but until you share it more widely you must be in the origination workspace to reveal, change, share, or delete it.

Share a shared vault secret

To share a secret, you must either have created it or hold the team-level Security Manager role. A Security Manager can share any secret on the team, including secrets scoped to workspaces they aren’t a member of. Teammates you share a secret with can use its value in their requests, but only its creator and a Security Manager can reveal the value.

Until a secret is shared with specific teammates or your entire team, you must be in its origination workspace to share it.

To share a vault secret, do the following:

1. Open your workspace’s shared vault.

2. Hover over the secret and click Share.

3. Under Who can access this secret, select one of the following:

   • Specific to this workspace only — (Default) Only members of the origination workspace can use it. If you change the scope, anyone in the origination workspace will still be able to use the secret. To revoke access from the workspace, delete the secret and start over. This option is unavailable if the secret is already shared with specific teammates or your entire team.
   • Share with user and members of origination workspace — Share the secret with specific teammates, including those outside the workspace. Everyone in the workspace keeps access. In Teammates, search for each teammate by name or email, then select them from the list. Each teammate you add appears as a chip you can remove. This option is unavailable if the secret is already shared with your entire team.
   • All team members — Everyone on this team can use this secret. You can’t narrow the scope back to specific teammates later. To revoke access from the team, delete the secret and start over.

4. Click Save changes.

Access scopes only widen. An option you can no longer select is unavailable rather than hidden, so you can still see which scopes exist. The secret’s Shared with column updates to show its new access scope.

Understand the Shared with column

Your shared vault shows each secret’s access scope in the Shared with column:

Request access to a shared vault secret

Any team member can request access to a secret that hasn’t been shared with them. Those secrets show a Request access button in place of the usual actions.

To request access to a secret, do the following:

1. Open your workspace’s shared vault, then click Secrets > Postman vault.
2. Click Request access for the secret you want to use. The button changes to Requested and becomes unavailable.
3. Postman notifies the secret’s creator that you requested access. Your request also appears under Access Requests > Needs my approval for anyone who can approve it.
4. To track your pending requests, click Access Requests > My requests.

Postman notifies you when the secret’s creator or a Security Manager approves or denies your request.

Approve or deny access to a shared vault secret

A secret’s creator and any Security Manager can approve or deny requests to access it. You can respond from the Postman notification, which has Approve and Deny buttons, or from your shared vault.

To respond to a request from your shared vault, do the following:

1. Open your workspace’s shared vault.
2. Click the Access Requests tab.
3. On Needs my approval, review the request. Each one lists the requester, the secret, the secret’s current access scope, when it was requested, and its status. A request that’s waiting on you shows Pending.
4. Click Approve or Deny.

To respond to several requests at once, select the checkbox next to each one, then click Approve selected or Deny selected. Postman reports how many were updated, how many were already handled, and how many failed.

Approving a request shares the secret with that teammate. Postman notifies them, and the secret’s Shared with column updates to include them.

You can’t approve your own requests, and they don’t appear under Needs my approval even when you could otherwise approve requests for that secret.

View a secret’s value

Shared vault secret values are masked everywhere in Postman, and only a secret’s creator and a Security Manager can reveal one. Teammates a secret is shared with can use its value in their requests without being able to read it.

Until a secret is shared with specific teammates or your entire team, you must be in its origination workspace to reveal its value.

To view a secret’s value, do the following:

1. Open your workspace’s shared vault.
2. To find a specific secret, search the list by key name, or filter it by workspace or creator.
3. Hover over a secret to show its actions.
4. Click View value, then click the Show password icon to reveal the value.

Edit a shared vault secret

You can edit a secret you created, and a Security Manager can edit any secret on the team.

Until a secret is shared with specific teammates or your entire team, you must be in its origination workspace to edit it.

To edit a secret, do the following:

1. Open your workspace’s shared vault.
2. To find a specific secret, search the list by key name, or filter it by workspace or creator.
3. Hover over a secret to show its actions.
4. Click Edit secret.
5. Update the secret’s key name, value, allowed domains, or access scope, then click Save changes. The fields are the same ones described in Create a shared vault secret.

Because a Security Manager can reveal and change any secret’s value, a secret can still be rotated if the creator leaves your team.

Delete a shared vault secret

Deleting a secret removes it from your workspace’s shared vault for everyone it was shared with. Deleting is also the only way to fully revoke access to a secret that’s shared with a workspace or your entire team.

Until a secret is shared with specific teammates or your entire team, you must be in its origination workspace to delete it.

To delete a secret, do the following:

1. Open your workspace’s shared vault.
2. To find a specific secret, search the list by key name, or filter it by workspace or creator.
3. Hover over a secret to show its actions.
4. Click Delete, then click Delete to confirm.

Deleting a secret doesn’t remove the secure variables that reference it, or references to those variables in your requests. To fully remove the secret and stop using it, also delete the secure variable, in its global, environment, or collection scope, and each reference to that variable in your requests. Until you do, requests that use the variable are unresolved.