# Configure a Connection with HashiCorp Vault

Source: https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/how-tos/configure-connection/

This page walks through the **Secrets Management** group of the connection form and the `${key}` references that use the secret. It applies to every connector; the connector's own page documents the rest of its form.

> **Tip: No secret, policy, or role yet?**
>
> Set them up first in [Prepare Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/how-tos/prepare-vault/). The values you need here come out of those steps.

Before you start, confirm with your network team that the addresses listed below the connection form can reach Vault, and that Vault's hostname resolves from inside the Qualytics deployment. See [Network Requirements](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/how-it-works/#network-requirements).

## Steps

**Step 1**: Start adding a datastore and choose **New Connection**. Secrets management belongs to the connection, so it is read-only when you reuse an existing one.

**Step 2**: Under **Secrets Management**, turn on **HashiCorp Vault**.

**Step 3**: Fill in the six fields. The values below match the example in Prepare Vault; replace the host, namespace, mount, and secret name with yours.

| Field | Value |
| --- | --- |
| **Login URL** | `https://vault.example.com/v1/auth/approle/login`, or `https://vault.example.com/v1/<namespace>/auth/approle/login` when the AppRole lives in a namespace |
| **Credentials Payload** | `{"role_id": "<role_id>", "secret_id": "<secret_id>"}` |
| **Token JSONPath** | `$.auth.client_token` |
| **Secret URL** | `https://vault.example.com/v1/secret/data/qualytics/postgres`, or with the namespace after `/v1/`. Build it from the **API path** on the secret's **Paths** tab, with `https://` and the host in front |
| **Token Header Name** | `X-Vault-Token` |
| **Data JSONPath** | `$.data.data` for a KV version 2 secret (its API path contains `/data/`); `$.data` for KV version 1 or the database secrets engine. Change the pre-filled `$.data` if needed |

Both URLs must be complete, starting with `https://` and including the host. A bare path is not accepted.

**Step 4**: In the **Connection Properties** and **Authentication** fields, enter `${key}` wherever a value should come from the secret, for example `${username}` and `${password}`. Use braces, not `$.key`, and match the key name's case exactly. Only names made of letters, digits, and underscores, starting with a letter or underscore, can be referenced; see [Referencing the Secret](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/how-it-works/#referencing-the-secret).

**Step 5**: Fill in the connector's remaining fields as documented on its page, then click **Test connection**. A successful test means Qualytics logged in to Vault, read the secret, substituted every reference, and reached the data source with the result.

**Step 6**: If the test fails, match the message in the banner to its entry in [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/troubleshooting/), fix the cause, and test again.

**Step 7**: Click **Next** to continue with the datastore, then **Finish**.

> **Tip: Changing a credential later**
>
> Change it in Vault. Qualytics fetches the secret every time the connection is opened, so nothing needs to be edited here. If you rotate the AppRole secret ID, update only the **Credentials Payload**.

*Last updated: October 7, 2026.*
