> This page is for Postman Docs, version Latest (v12) (default). > For other versions, use one of these documentation indexes: > - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt > - v11: https://learning.postman.com/v11/llms.txt > For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # Integrate Postman Shared Vault with HashiCorp Vault > **Info** > > This feature is available on Postman Enterprise plans with the Advanced Security Administration add-on. For more information, see the [pricing page](https://www.postman.com/pricing/). Connect [Postman Shared Vault](/docs/use/postman-vault/postman-vault-key/#postman-shared-vault) to [HashiCorp Vault](https://developer.hashicorp.com/vault/docs/what-is-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. > **Info** > > This page covers Postman Shared Vault, which an admin sets up once for the team. To set it up from your own vault instead, see [Integrate Postman Local Vault with HashiCorp Vault](/docs/use/postman-vault/hashicorp-vault/). ## Who does what \[#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](/docs/administration/roles-and-permissions#team-roles)** 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. | Task | Who does it | How often | | :-------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | :---------------------------------------------- | | [Add the HashiCorp Vault connection](#add-a-hashicorp-vault-connection) | Admin, Super Admin, or Security Manager | Once per connection | | [Configure an authentication method](#configure-an-authentication-method) | Admin, Super Admin, or Security Manager | Once per method. Revisit to rotate credentials. | | [Create a linked key from a HashiCorp secret](#link-a-shared-vault-key-to-a-hashicorp-secret) | Workspace Editor, Security Manager, or Super Admin | Once per secret | | [Use the linked key in a request](#use-the-linked-key-in-a-request) | Anyone the linked key is shared with: its workspace, specific people, or the whole team | Ongoing | ## About the HashiCorp Vault integration \[#about-the-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: | Authentication method: | AppRole (machine) | OIDC (per-user SSO) | | :----------------------------- | :------------------------------------------ | :------------------------------------------------ | | **Use it for** | Monitors and other unattended runs | Sending requests from the Postman desktop app | | **Identity used** | The connection's AppRole identity | The team member's own identity in HashiCorp Vault | | **Credentials Postman stores** | The Role ID and Secret ID, stored encrypted | None | 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 \[#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 \[#which-authentication-method-resolves-a-linked-key] The authentication method used to resolve a linked key's value depends on where the request runs: | Where the request runs | Authentication method used | Notes | | :------------------------------------------------------------------------------------------------------------------------- | :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Postman desktop app: sending a request, running a flow from the canvas, or running a collection with the Collection Runner | OIDC (per-user) | Resolves on your device, with your own HashiCorp Vault access. Postman's servers don't call HashiCorp Vault for this method. | | Postman web app | Not supported | The variable shows **This secret resolves only in the Postman desktop app**, and the request uses an empty string or the literal `{{variable-name}}`. | | Monitors, including ones that run on a runner in your own network | AppRole (machine) | Resolves through Postman's vault service, over TLS, and is never stored. A runner in your network also calls Postman's vault service to resolve the secret. | | Scheduled collection runs (Postman Cloud) | AppRole (machine) | Resolves through Postman's vault service, over TLS, and is never stored. | | Postman CLI (`collection run`, `request`, or `environment get`, with an API key or after `postman login`) | AppRole (machine) | Includes CLI runs in a CI pipeline. Postman checks that the user can use the linked key, then reads it with the AppRole. The user's own HashiCorp Vault access isn't checked. | | Deployed flows and flow actions (Postman Cloud) | AppRole (machine) | Resolves through Postman's vault service, over TLS. | ## Prepare HashiCorp Vault \[#before-you-start] 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](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v1) or [version 2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2)) containing at least one secret, and an [ACL policy](https://developer.hashicorp.com/vault/docs/concepts/policies) that grants `read` access to the secret's path. If you use Vault Enterprise or HCP Vault Dedicated, also note the [namespace](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) that contains them. Open source HashiCorp Vault doesn't use namespaces. Postman reads a KV version 2 secret at `GET /v1//data/`, and adds `?version=N` when you pin a version. It reads a KV version 1 secret at `GET /v1//`. Grant `read` on the matching path. For KV version 2, the policy path includes a `data/` segment. For example: ```hcl # 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 \[#prepare-approle] To prepare HashiCorp Vault for the AppRole method, do the following: 1. Enable HashiCorp Vault's [AppRole auth method](https://developer.hashicorp.com/vault/docs/auth/approle) 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](/docs/use/postman-vault/shared-vault-manage-integrations/#edit-an-authentication-method) on the method. ### OIDC method \[#prepare-oidc] 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](https://developer.hashicorp.com/vault/docs/auth/jwt) 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. > **Info** > > Each authentication method resolves secrets with a different identity, so each one needs its own read access in HashiCorp Vault. An ACL policy that covers a member's own identity in HashiCorp Vault doesn't apply to the AppRole identity. ## Add a HashiCorp Vault connection \[#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](/docs/use/postman-vault/postman-vault-key/#manage-access-to-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**. > **Warning** > > You can't change a connection's **Server URL** or display name after you create it. To point at a different server, delete the connection and create a new one. 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. > **Info** > > To confirm that a secret resolves, send a request or run a monitor that uses a linked key. ## Configure an authentication method \[#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. > **Info** > > Team settings opens in your web browser, so you create and configure connections there. A connection or method change doesn't reach a Postman desktop app that's already open until members select **Help > Clear Cache and Reload** or restart Postman. Until then, members who are already signed in keep using the previous settings. ### AppRole (machine) \[#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**. > **Warning** > > Postman doesn't verify these credentials when you save them, and there's no test action for an individual method. The first time they're checked is when something reads a secret. If the Role ID or Secret ID is wrong, or the AppRole's ACL policy doesn't grant read access to the secret, the method still saves and resolution fails later. 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](/docs/use/postman-vault/shared-vault-manage-integrations/#edit-an-authentication-method) 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) \[#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 \[#link-a-shared-vault-key-to-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](/docs/use/postman-vault/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**. > **Info** > > A HashiCorp secret can hold more than one field. **Field selector** is required when the secret has multiple fields, because Postman resolves a key to a single value. The selector must start with a forward slash, and the field it points to must hold a single value, not an object or list. 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. > **Warning** > > Postman doesn't contact HashiCorp Vault when you create a linked key, so it can't check the location. A wrong mount, path, field, or version only fails later, when Postman tries to read the secret. 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 \[#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 ![Unlock icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-descriptive-unlock-stroke.svg#icon) **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. > **Warning** > > When a linked key can't be resolved, the request uses an empty string or the literal `{{variable-name}}` instead, and nothing reports an error. This happens if you haven't signed in, if HashiCorp Vault denies access, if the secret doesn't exist, or if you send the request from the Postman web app. The same applies in monitors, scheduled runs, the Postman CLI, and deployed flows. [Sign in on your device](#sign-in-to-resolve-secrets-on-your-device) in the Postman desktop app, and check the ACL policy of the member or the AppRole. ### Sign in to resolve secrets on your device \[#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 \[#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](/docs/use/postman-vault/shared-vault-manage-integrations/). ## What's stored and how it's protected \[#security] | Data | Where it's stored | How it's protected | | :------------------------------------------------------------------------- | :------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Secret values | Not stored by Postman. Read from HashiCorp Vault at use time. | Postman desktop app: held in memory only, for up to 60 minutes, then re-fetched. Monitors: fetched when the run starts. CLI: fetched per request. Never cached on Postman's servers. | | AppRole Role ID and Secret ID | The vault service's database, as ciphertext | Encrypted with envelope encryption: AES-256-GCM using a data key generated and wrapped by AWS KMS. Stored write-only. If your team uses [BYOK](/docs/administration/managing-your-team/byok-encryption/), Postman uses your team's own AWS KMS key. | | OIDC settings (issuer URL, client ID, auth mount path, Vault role, scopes) | The vault service's database, as plain configuration | Not treated as secret. No credentials are stored for this method. | | Server URL and namespace | The vault service's database, as plain configuration | Not treated as secret. Every team member can see them. | | Secret location | The vault service's database, in the linked key's row | Encrypted at rest. It isn't itself a secret. Anyone who can open Shared Vault can see it, for any linked key. | | Member's HashiCorp Vault token (OIDC method) | The Postman desktop app's memory, on that device only | Never written to disk, and never sent to Postman. | ## Next steps * To learn how connections and authentication methods work, see [Integrate Postman Shared Vault with external vaults](/docs/use/postman-vault/shared-vault-integrations/). * To learn how to reference vault secrets, see [Use vault secrets](/docs/use/postman-vault/use-vault-secrets/). * To learn how to troubleshoot vault secrets, see [Troubleshoot vault secrets](/docs/use/postman-vault/troubleshoot-vault-secrets/).