> 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 Azure Key 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 [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) so linked keys can read their values from secrets your team already stores in Azure. Postman stores only a reference to the secret, called the secret identifier. The value stays in Azure Key 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 Azure Key Vault](/docs/use/postman-vault/azure-key-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 (service principal, Microsoft Entra user, or both). This is a one-time task. Members still need a Key Vault role in Azure to use linked keys in the desktop app, and your tenant may need an Entra admin to consent to Postman's app once. * **Workspace Editors, Security Managers, and Super Admins** create a linked key that resolves its value from an Azure 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 Azure Key Vault connection](#add-an-azure-key-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 an Azure secret](#link-a-shared-vault-key-to-an-azure-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 Azure Key Vault integration \[#about-the-integration] An integration has two parts: * A **connection** identifies which Microsoft Entra directory (tenant) to read from. One connection can read from any key vault in that directory, because each linked key names its own vault. 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 Azure when it reads a secret. A connection can have one, or both, of the following methods: | Authentication method: | Microsoft Entra user | Service principal | | :----------------------------- | :--------------------------------------------- | :----------------------------------------------------------------------------------- | | **Use it for** | Sending requests from the Postman desktop app | Monitors and other unattended runs | | **Identity used** | The team member's own Microsoft Entra identity | An app registration's identity, stored on the connection | | **Credentials Postman stores** | None | The client secret, stored encrypted. The client ID is stored as plain configuration. | A connection with only one method can only do that method's job. A connection with only the Microsoft Entra user method can't resolve secrets in monitors. A connection with only the service principal method can't resolve secrets for requests members send themselves. To support both, configure both methods. ### How access works \[#how-access-works] The service principal is the connection's identity, not a person's. Its role in Azure 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 service principal method reads secrets with the service principal's Key Vault role, not the member's. For this reason, grant the service principal access to only the secrets you want to share with your team, ideally in a dedicated key vault. To have Azure check each member's own access instead, configure only the Microsoft Entra user 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 | Microsoft Entra user (per-user) | Resolves on your device, with your own Key Vault access. Postman's servers don't call Azure 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 | Service principal (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) | Service principal (machine) | Resolves through Postman's vault service, over TLS, and is never stored. | | Postman CLI (`collection run` or `request`, with an API key or after `postman login`) | Service principal (machine) | Includes CLI runs in a CI pipeline. Postman checks that the user can use the linked key, then reads it with the service principal. The user's own Azure role isn't checked. | | Deployed flows and flow actions (Postman Cloud) | Service principal (machine) | Resolves through Postman's vault service, over TLS. | ## Prepare Azure \[#before-you-start] Before you add the connection in Postman, complete the following setup in Azure. You need a key vault with at least one secret, and the tenant ID of the directory that owns it. If you don't have a secret yet, [create one](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal#add-a-secret-to-key-vault). To find the tenant ID, go to **Microsoft Entra ID > Overview** in the Azure portal. Only the Azure public cloud is supported. > **Warning** > > Creating a key vault makes you its owner, but ownership doesn't grant permission to read the secrets inside it. Without a data-plane role such as Key Vault Secrets User, setup appears to succeed and secrets fail to resolve later. > **Info** > > The service principal method reads secrets from Postman's cloud, which has no published IP addresses. A Key Vault firewall that allows only your IP addresses therefore blocks monitors, scheduled runs, the Postman CLI, and deployed flows, and the service principal method can't reach a key vault behind a Private Endpoint. This includes monitors on a runner in your own network, because the runner still resolves secrets through Postman's vault service. The Microsoft Entra user method reads secrets from each member's machine, so it works behind a firewall, including a key vault behind a Private Endpoint that the member's machine can reach. Complete one of the following, depending on which authentication method you plan to configure. ### Service principal method \[#prepare-service-principal] To begin, you must have an Azure administrator [register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the same directory as the connection. To prepare Azure for the service principal method, do the following: 1. Set the application type to **single-tenant** (labeled **Single tenant only** or **Accounts in this organizational directory only**, depending on your Azure portal version). Single-tenant is the simplest setup. A multi-tenant application also works if it has a service principal in the connection's directory. The application doesn't need a redirect URI. 2. Create a client secret on the application. Only client secrets are supported. 3. From the key vault's **Access control (IAM)** settings, grant the application's service principal at least the [Key Vault Secrets User](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) role. If your key vault uses the legacy access policy model instead of Azure RBAC, add an access policy granting **Get** permission on secrets instead. Grant the role only on the key vaults or secrets you want to share with your team through Postman. Anyone who can create a linked key can pick any secret this application can read. ### Microsoft Entra user method \[#prepare-entra-user] You don't need to register an application in Azure for this method. By default, sign-in uses Postman's own multi-tenant Microsoft Entra application (`ea8d5e35-ebe1-4a78-a632-6804b6d5e296`), so members who can't register applications in your directory can still use it. If your tenant restricts user consent, the first member to sign in sees **Need admin approval** until an Entra admin grants consent to this application once. Register your own application only if your organization requires it. For example, for its own Conditional Access policies, consent screen branding, or a policy that bans third-party multi-tenant applications. To use your own application, register it in the connection's directory, add the **Mobile and desktop applications** platform with the redirect URI `http://127.0.0.1` (not Web), add the delegated permission **Azure Key Vault > user_impersonation**, and grant admin consent if your tenant requires it. Then enter its client ID as the **Custom app (client) ID**. To prepare Azure for the Microsoft Entra user method, grant each member who'll use this method at least the **Key Vault Secrets User** role on the key vault. If your key vault uses the legacy access policy model instead, grant the equivalent **Get** permission on secrets. This role applies to the Microsoft Entra user method, which the Postman desktop app uses. Monitors, scheduled runs, the Postman CLI, and deployed flows use the service principal's role instead. ## Add an Azure Key Vault connection \[#add-an-azure-key-vault-connection] As a Postman Admin, Super Admin, or Security Manager, you create the connection once for your team. To add an Azure Key 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 **Azure Key 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 **Directory (tenant) ID** of the Microsoft Entra directory that owns your key vaults. It's a GUID, such as `00000000-0000-0000-0000-000000000000`. 7. Click **Create connection**. > **Warning** > > You can't change a connection's **Directory (tenant) ID** after you create the connection. To point at a different directory, delete the connection and create a new one. The connection card shows its name, **Azure Key Vault** with the tenant ID, 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 confirm that Postman can reach your directory, click **Check reachability** on the connection. A status of **Reachable** means the directory exists and Microsoft Entra responded. It only confirms that the tenant ID belongs to a real directory. > **Info** > > **Check reachability** doesn't use the credentials you configure, and it doesn't confirm that an identity can read a secret. Confirm that by sending a request or running 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. ### Service principal (client secret) \[#service-principal-client-secret] Configure the service principal method for machine use, such as monitors and other unattended runs. It uses the application registration's identity rather than an individual member's. To configure the service principal method, do the following: 1. Click **Configure** next to **Service principal (client secret)** on the connection. 2. Enter the **Application (client) ID** of the app you registered in this connection's directory. You can find it on the app's **Overview** page. It's a GUID. 3. Enter the **Client secret** value you created on that app. In the app's **Certificates & secrets**, copy the **Value** column, not the **Secret ID**. Azure shows the value only once, right after you create it. 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 application isn't registered in this connection's directory, or the client secret is wrong or expired, the method still saves and resolution fails later. Client secrets expire in Azure. When one expires, create a new client secret in Azure, then [replace the credential](/docs/use/postman-vault/shared-vault-manage-integrations/#edit-an-authentication-method) on the method. Postman stores the client secret write-only and can't display it, so replacement is the only way to change it. ### Microsoft Entra user (sign in on this device) \[#microsoft-entra-user-sign-in-on-this-device] Configure the Microsoft Entra user method for per-user use, so each member resolves secrets with their own Microsoft Entra identity and Key Vault access. No credentials are stored for this method. To configure the Microsoft Entra user method, do the following: 1. Click **Configure** next to **Microsoft Entra user (sign in on this device)** on the connection. 2. (Optional) Enter a **Custom app (client) ID** to use your own Entra app instead of Postman's. To set it up, see [Microsoft Entra user method](#prepare-entra-user). 3. Click **Configure**. > **Info** > > This form has no required fields. Leave **Custom app (client) ID** empty to use Postman's own multi-tenant Entra app, which is the expected setup for most teams. 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 an Azure secret \[#link-a-shared-vault-key-to-an-azure-secret] Workspace Editors, Security Managers, and Super Admins can create a linked key that resolves from an Azure secret. Each workspace has its own shared vault, so create the linked key in the workspace where you want to use it. Before you link a key, copy the secret's identifier from Azure. In the Azure portal, open your key vault, select **Objects > Secrets**, select the secret, then select its current version and copy the **Secret Identifier**. It's a URL in the following format: ```txt wordWrap https://.vault.azure.net/secrets// ``` > **Info** > > Omit the trailing version ID to always read the secret's latest value. Include it to pin the key to that specific version. The vault name is 3–24 letters, digits, and hyphens, starting with a letter and ending with a letter or digit. The secret name is up to 127 letters, digits, and hyphens. The version ID is 32 hexadecimal characters. Postman rejects a trailing slash, a query string, a fragment, a port, user credentials, an `http://` URL, and any host other than `*.vault.azure.net`. To create a linked key that resolves from an Azure 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 **Secret identifier** you copied from Azure. 9. Click **Link secret**. The linked key appears under its connection on the **External vaults** tab. To see which Azure secret it points to, click **View value**. The reference shows the vault name, the secret name, and the first 8 characters of the version ID, such as `my-vault/db-password@e931b0b8`. > **Warning** > > Postman doesn't contact Azure when you create a linked key, so it can't check the identifier. A wrong vault name, secret name, or version, a deleted secret, or a vault in a different directory only fails later, when Postman tries to read the secret. ## 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 Azure denies access, if the secret is turned off or expired, 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 Key Vault role of the member or the service principal. ### 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 Microsoft Entra user authentication method in the Postman desktop app, sign in to the connection that owns the key. The service principal 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. Whichever way you start, sign in with a Microsoft Entra account from the connection's directory. Your browser opens Microsoft sign-in for that directory. Complete the sign-in within 5 minutes, or the sign-in times out and you'll need to start over. 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. > **Info** > > Postman scopes the sign-in to the directory the connection specifies, so an account in a different directory can't resolve its secrets. Sign-in is per connection, so keys linked through two Azure connections need two separate sign-ins. The following also apply: * The session token lives in the Postman desktop app's memory only. It's never written to disk and never reaches Postman. * Restarting Postman or reloading the window ends the session, and you'll need to sign in again. * Signing out clears the token and every cached value for that connection. * Resolved values are cached on the device for up to 60 minutes. Sign out and back in to force a fresh read. After a secret is rotated in Azure, a linked key without a version ID can return the previous value for up to 60 minutes. * Requests still go through Postman's request engine, so your proxy and certificate settings apply. The Microsoft sign-in page opens in your system browser, so the browser's network settings apply there. Restart Postman after you change proxy or certificate settings. ## 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 Azure at use time. Synced request history can still contain a value if the team turns off secret masking, or if an API returns it in a response. | 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. | | Service principal client secret | The vault service's database, as ciphertext | Encrypted with envelope encryption: AES-256-GCM using a data key generated and wrapped by AWS KMS. If your team uses [BYOK](/docs/administration/managing-your-team/byok-encryption/), Postman uses your team's own AWS KMS key. | | Secret identifier | The vault service's database, in the linked key's row | Encrypted at rest with the same envelope and key policy. It isn't itself a secret. Anyone who can open Shared Vault can see it, for any linked key. | | Client IDs and the tenant ID | The vault service's database, as plain configuration | Not treated as secret. Every team member can see them. | | Member's Microsoft token (per-user method) | The Postman desktop app's memory, on that device only | Never written to disk, and never sent to Postman. | | Who can read a value | Anyone who can use the linked key, for example from a script or the Postman CLI | Key sharing decides who can use it. Allowed domains limit where it can be sent. | | Audit | The team audit log | Records connection and linked-key changes. Azure's logs show the member for desktop reads and the service principal for all other reads. | ## 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/).