Integrate Postman Shared Vault with HashiCorp Vault

Connect Postman Shared Vault to HashiCorp Vault so linked keys can read their values from secrets your team already stores in HashiCorp Vault.

Postman stores only a reference to the secret, called the secret location: the secrets engine mount, KV version, secret path, and optional field and version. The value stays in HashiCorp Vault, and Postman fetches it when you send a request or run a monitor.

Who does what

Setting up the integration and using it are two separate jobs, done by different people:

• A user with Postman Admin, Super Admin, or Security Manager permission sets up the connection for the team. They also configure at least one authentication method (AppRole, OIDC, or both). This is a one-time task. Members still need read access in HashiCorp Vault to use linked keys in the desktop app.
• Workspace Editors, Security Managers, and Super Admins create a linked key that resolves its value from a HashiCorp secret, then use it in requests. This happens on an ongoing basis, once per secret you want to use.

About the HashiCorp Vault integration

An integration has two parts:

• A connection identifies which HashiCorp Vault server to read from, and optionally one namespace within it. One connection can read any secret your team’s access allows on that server. A connection belongs to your whole team, but the keys that use it live in individual workspaces, so one connection can serve linked keys in many workspaces.
• An authentication method determines how Postman identifies itself to HashiCorp Vault when it reads a secret. A connection can have one, or both, of the following methods:

A connection with only one method can only do that method’s job. A connection with only the AppRole method can’t resolve secrets for requests members send themselves. A connection with only the OIDC method can’t resolve secrets in monitors. To support both, configure both methods.

How access works

The AppRole is the connection’s identity, not a person’s. Its ACL policy decides which secrets Postman can reach for your team. Postman decides who can use each one:

• Permission to create linked keys decides who can bring one of those secrets into Postman.
• A linked key’s sharing decides which members and runs can use it. Anyone who can use a linked key can read its value.
• Allowed domains limit where the value can be sent.

The AppRole method reads secrets with the ACL policy attached to the AppRole, not the member’s. For this reason, grant the AppRole read access to only the secrets you want to share with your team. To have HashiCorp Vault check each member’s own access instead, configure only the OIDC method. Linked keys on that connection then don’t resolve in monitors, scheduled runs, the Postman CLI, or deployed flows.

Monitors, scheduled collection runs, performance tests, self-hosted runners, and deployed flows don’t run as a team member. In these, a linked key resolves only if it’s shared with your whole team, or if it was created in the same workspace as the monitor or run. A key that’s shared only with specific teammates doesn’t resolve in them.

Which authentication method resolves a linked key

The authentication method used to resolve a linked key’s value depends on where the request runs:

Prepare HashiCorp Vault

Before you add the connection in Postman, complete the following setup in HashiCorp Vault.

You need the base URL of your HashiCorp Vault server, a KV secrets engine (version 1 or version 2) containing at least one secret, and an ACL policy that grants read access to the secret’s path. If you use Vault Enterprise or HCP Vault Dedicated, also note the namespace that contains them. Open source HashiCorp Vault doesn’t use namespaces.

Postman reads a KV version 2 secret at GET /v1/<mount>/data/<path>, and adds ?version=N when you pin a version. It reads a KV version 1 secret at GET /v1/<mount>/<path>. Grant read on the matching path. For KV version 2, the policy path includes a data/ segment. For example:

# KV version 2
path "secret/data/*" {
  capabilities = ["read"]
}
# KV version 1
path "secret/*" {
  capabilities = ["read"]
}

The AppRole method reads secrets from Postman’s cloud. For monitors, scheduled runs, performance tests, self-hosted runners, the Postman CLI, and deployed flows to resolve secrets, your HashiCorp Vault server must meet the following requirements:

• The server is reachable from the public internet at a public IP address. Postman’s cloud has no published IP addresses. This also applies to runners in your own network, because Postman’s vault service, not the runner, reads the secret.
• The server uses HTTPS with a certificate from a publicly trusted certificate authority. Self-signed certificates and private certificate authority certificates aren’t supported.

The OIDC method reads secrets from each member’s machine, so it works behind a firewall if members can reach the server, such as over a VPN.

Complete one of the following, depending on which authentication method you plan to configure.

AppRole method

To prepare HashiCorp Vault for the AppRole method, do the following:

1. Enable HashiCorp Vault’s AppRole auth method if it isn’t already enabled. The default mount path is approle.
2. Create an ACL policy that grants read on the secret’s path, as described above.
3. Create an AppRole role whose token policies include that ACL policy, then generate a Role ID and Secret ID. Grant the role access to only the secrets you want to share with your team, because anyone who can create a linked key can pick any secret this AppRole can read.

Secret IDs can expire, depending on how the AppRole is configured. When one expires, generate a new Secret ID in HashiCorp Vault, then replace the credentials on the method.

OIDC method

The OIDC method lets each member resolve secrets with their own identity in HashiCorp Vault. It needs three things in your environment:

• An OpenID Connect identity provider with a public client registered for Postman, such as a native app that uses PKCE and has no client secret. For your own provider, such as Okta or Microsoft Entra, add the Postman desktop app’s redirect URI exactly as shown, including the trailing slash: http://127.0.0.1:10534/. Most identity providers reject the sign-in if the registered URI differs in any way, such as localhost instead of 127.0.0.1.

• A HashiCorp Vault JWT/OIDC auth method that trusts that provider, with its oidc_discovery_url set to the provider’s issuer URL.

• A HashiCorp Vault role on that auth mount that maps a signed-in member to an ACL policy that grants read access, with bound_audiences set to the OIDC client ID and user_claim set to a claim such as sub.

If you use HashiCorp Vault’s own OIDC provider as your identity provider, each member also needs a HashiCorp Vault login to sign in with, such as a userpass account. A root token can’t sign in, because it has no HashiCorp Vault identity. With an external identity provider, such as Okta or Microsoft Entra, members sign in with their identity provider account.

Add a HashiCorp Vault connection

As a Postman Admin, Super Admin, or Security Manager, you create the connection once for your team.

To add a HashiCorp Vault connection, do the following:

1. Click Settings in the Postman header, then select Team settings.
2. Under Security & Governance, click Shared vault, then select the External vault integrations tab. If you see Turn on instead, turn on Postman Shared Vault for your team first.
3. Click Add connection.
4. Select HashiCorp Vault from the Provider dropdown list.
5. Enter a Display name to identify the connection in Postman. It must be unique in the team, ignoring case.
6. Enter the Server URL of your HashiCorp Vault server, such as https://vault.example.com. Include the port if it isn’t standard, such as https://vault.example.com:8200. The URL must start with https://.
7. (Optional) Enter a Namespace if you use Vault Enterprise or HCP Vault Dedicated. HCP Vault Dedicated uses the admin namespace or a namespace under it. Leave it blank for open source HashiCorp Vault.
8. Click Create connection.

The connection card shows its name, HashiCorp Vault with the server URL, and a section for each authentication method. A reachability status appears once someone on your team checks reachability. Until you configure an authentication method, the card reads Configure at least one method to enable secret resolution.

To check that Postman can reach your server, click Check reachability on the connection. Reachable means a server answered at that URL. It doesn’t confirm that the server is HashiCorp Vault, that it’s unsealed, or that any identity can read a secret.

Configure an authentication method

A new connection lists both authentication methods as Not configured, and it can’t resolve secrets until you configure at least one. Configure the method that matches how your team uses secrets, or configure both.

AppRole (machine)

Configure the AppRole method for machine use, such as monitors and other unattended runs. It uses the AppRole’s identity rather than an individual member’s.

To configure the AppRole method, do the following:

1. Click Configure next to AppRole (machine) on the connection.
2. Enter the Vault auth mount path where HashiCorp Vault’s AppRole auth method is enabled. The field defaults to approle.
3. Enter the Role ID and Secret ID for the AppRole.
4. Click Configure.

Secret IDs can expire in HashiCorp Vault, depending on how the AppRole is configured. When one expires, generate a new Secret ID in HashiCorp Vault, then replace the credentials on the method. Postman stores the Role ID and Secret ID write-only and can’t display them, so you enter both values together when you rotate either one.

OIDC (per-user SSO)

Configure the OIDC method for per-user use, so each member resolves secrets with their own identity and ACL policies in HashiCorp Vault. No credentials are stored for this method.

To configure the OIDC method, do the following:

1. Click Configure next to OIDC (per-user SSO) on the connection.
2. Enter the OIDC issuer URL of your identity provider. Postman discovers its endpoints from /.well-known/openid-configuration.
3. Enter the OIDC client ID registered with your identity provider for Postman.
4. Enter the Vault auth mount path where HashiCorp Vault’s JWT/OIDC auth method is enabled. The field defaults to jwt.
5. Enter the Vault role to authenticate with.
6. (Optional) Enter Additional scopes as a space-separated list, such as profile email. Postman always requests the openid scope.
7. Click Configure.

Once configured, the method’s status reads Available in the desktop app. Members sign in individually the first time they use a linked key.

Create a linked key from a HashiCorp secret

Workspace Editors, Security Managers, and Super Admins can create a linked key that resolves from a HashiCorp secret. Each workspace has its own shared vault, so create the linked key in the workspace where you want to use it.

A HashiCorp reference is made up of several fields that locate the secret and, when needed, pick one field out of it. Before you link a key, note the secrets engine mount, the KV version, the secret path, and the field you want.

To create a linked key that resolves from a HashiCorp secret, do the following:

1. In Postman, open a workspace.
2. Click Vault in the footer, and select Shared Vault.
3. Click the External vaults tab, next to Postman vault.
4. Click Link external secret.
5. Select a connection, then click Next. If only one connection is available, Postman skips this step.
6. Enter a Key name to reference the secret by in Postman. No spaces, {, or }.
7. (Optional) Enter Allowed domains to limit where the secret can be used, such as api.example.com, *.internal.example.com. By default, a linked key can be used in requests to any domain. To learn more, see Create and manage vault secrets.
8. Enter the Secrets engine mount where the secret is stored, such as secret.
9. Select the KV engine version that matches the secrets engine.
10. Enter the Secret path, such as app/prod/db.
11. (Optional) Enter a Field selector as a JSON Pointer to one field within the secret, such as /password.
12. (Optional) Enter a Secret version to read a specific version, or leave it blank to read the latest version. This field appears only when you select KV version 2.
13. Click Link secret.

The secrets engine mount is a single path segment, such as secret, so a nested mount such as team/kv isn’t supported. Secret path segments can contain letters, digits, periods, underscores, and hyphens.

The linked key appears under its connection on the External vaults tab. To see which secret it points to, click View value. Postman shows the reference as the mount, the secret path, and the field, such as secret/app/prod/db/password, and notes that the value is resolved from your provider at run time and isn’t stored in Postman. If you pin a version, Postman adds it to the end, such as secret/app/prod/db/password @v3.

Use the linked key in a request

You use a linked key by setting it as the value of a secure variable, then referencing that variable in your requests.

To use a linked key in a request, do the following:

1. Open a global, environment, or collection variable, then click Secure next to the variable name.
2. Leave the value empty, then click the value cell and select the linked key from your workspace’s shared vault.
3. To use the variable in the Postman Cloud, such as in a monitor, scheduled collection run, performance test, or the Postman CLI, hover over the value cell and click Share.
4. Reference the variable in your request using the {{variable-name}} syntax.

Sign in to resolve secrets on your device

Before you can resolve a linked key using the OIDC authentication method in the Postman desktop app, sign in to the connection that owns the key. The AppRole method isn’t used for requests you send from the desktop app. It only resolves linked keys in monitors, scheduled runs, the Postman CLI, and deployed flows.

Sign in from either of the following:

• In your workspace’s shared vault, open the External vaults tab, then click Sign in on this device next to the connection.
• Hover over the variable in your request. If you’re not signed in, a warning reads Sign in to resolve this secret, with options to sign in or open the shared vault.

Your browser opens your identity provider’s sign-in page. After you sign in and accept any consent prompt, the browser shows You’re authorized, and the connection’s group header shows Signed in with your account.

The following also apply:

• The HashiCorp Vault token lives in the Postman desktop app’s memory only. It’s never written to disk and never reaches Postman.
• Complete the sign-in within 5 minutes, or it times out and you start over.
• Postman renews your HashiCorp Vault token for as long as the ID token from your identity provider sign-in is valid, within the limits of your HashiCorp Vault role. After that, sign in again. Restarting Postman or reloading the window also ends the session.
• Signing out clears the token and every cached value for that connection.
• Resolved values are cached on the device for up to 60 minutes, per secret path. Sign out and back in to force a fresh read.
• The desktop app calls HashiCorp Vault directly, so the server must be reachable from your machine, such as over a VPN. Your proxy and certificate settings apply. Restart Postman after you change them.
• Sign-in is per connection, so keys linked through two HashiCorp connections need two separate sign-ins.

Manage the integration

After you create a connection, you can check its reachability, rotate or remove its authentication methods, update linked keys, and delete it. For these tasks, see Manage Shared Vault integrations.

What’s stored and how it’s protected

Next steps

• To learn how connections and authentication methods work, see Integrate Postman Shared Vault with external vaults.
• To learn how to reference vault secrets, see Use vault secrets.
• To learn how to troubleshoot vault secrets, see Troubleshoot vault secrets.