# How HashiCorp Vault Secrets Management Works

Source: https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/how-it-works/

This page explains what Qualytics does with the six **Secrets Management** fields, which values are right for each kind of Vault secret, how the connection fields reference the secret, and what the network must allow. The step-by-step setup lives in the how-tos: [Prepare Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/how-tos/prepare-vault/) and [Configure the Connection](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/how-tos/configure-connection/).

## The Four Steps

Each time Qualytics opens the connection, including connection tests, syncs, profiles, and scans, it performs these steps:

1. **Log in.** Qualytics sends a `POST` to the **Login URL** with the **Credentials Payload** as the request body.
2. **Extract the token.** The **Token JSONPath** is applied to the login response to read the client token.
3. **Fetch the secret.** Qualytics sends a `GET` to the **Secret URL** with the token in the header named by **Token Header Name**.
4. **Substitute.** The **Data JSONPath** is applied to the fetch response to obtain a flat object of key/value pairs. Every `${key}` in the connection's fields is replaced with the matching value.

Secrets are never cached between uses. That is what makes a credential changed in Vault take effect automatically, and it is also why Vault must stay reachable for as long as the datastore is in use. The one thing Qualytics remembers is a failure to reach Vault: after a connection or name resolution failure, it does not contact that host again for five minutes, and a test or operation in that window fails right away with a message saying how long ago the failure was and when the next try happens.

## The Six Fields

| Field | Example for an AppRole login and a KV version 2 secret | Notes |
| --- | --- | --- |
| **Login URL** | `https://vault.example.com/v1/auth/approle/login` | A full URL with scheme and host. With a namespace: `https://vault.example.com/v1/<namespace>/auth/approle/login`. |
| **Credentials Payload** | `{"role_id": "<role_id>", "secret_id": "<secret_id>"}` | Any valid JSON the login endpoint accepts. The namespace never goes here; it goes in the URLs. |
| **Token JSONPath** | `$.auth.client_token` | Correct for every Vault auth method. Other products put the token elsewhere; check their login response. |
| **Secret URL** | `https://vault.example.com/v1/secret/data/qualytics/postgres` | A full URL: scheme, host, then the API path shown on the secret's **Paths** tab in the Vault UI. With a namespace: `https://vault.example.com/v1/<namespace>/secret/data/qualytics/postgres`. |
| **Token Header Name** | `X-Vault-Token` | Vault's header. Other products use their own, for example `Authorization`. The extracted token is sent as the header value exactly as returned, with nothing added. |
| **Data JSONPath** | `$.data.data` | Depends on the engine serving the secret; see below. The form pre-fills `$.data`, which is right only for KV version 1 and the database secrets engine. |

Any Vault auth method that answers a `POST` with a token works, not only AppRole: user and password, LDAP, Okta, GitHub, and others all return the token at `$.auth.client_token`. AppRole is the usual choice for a service like Qualytics because it does not depend on a person's account.

> **Note: Header value is sent verbatim**
>
> Qualytics puts the value the **Token JSONPath** extracted into the header unchanged. A product that expects `Authorization: Bearer <token>` but returns only the bare token in its login response will reject the fetch, because no `Bearer` prefix is added. Such a product needs a login endpoint, or a gateway in front of it, that returns the complete header value.

## Choosing the Data JSONPath

The Data JSONPath must point at the object that holds the key/value pairs, and that object sits at a different depth depending on the engine that serves the secret.

| Engine | How to recognize it | Fetch response shape | Data JSONPath |
| --- | --- | --- | --- |
| KV version 2 (the default for new mounts) | The API path contains `/data/`, for example `/v1/secret/data/qualytics/postgres` | `{"data": {"data": {"username": "...", "password": "..."}, "metadata": {...}}}` | `$.data.data` |
| KV version 1 | No `/data/` segment, for example `/v1/kv/qualytics/postgres` | `{"data": {"username": "...", "password": "..."}}` | `$.data` |
| Database secrets engine (dynamic credentials) | The path starts with `/v1/database/creds/` | `{"data": {"username": "...", "password": "..."}}` | `$.data` |

With `$.data` on a KV version 2 secret, Qualytics receives an object whose only keys are `data` and `metadata`, so every `${key}` reference fails with a message listing exactly those two keys.

### JSONPath Expressions for Custom Responses

Choose a path that selects exactly one token for **Token JSONPath** and one object of key/value pairs for **Data JSONPath**. Qualytics uses the first match when an expression matches several values, so an explicit path is safer than a wildcard.

For example, if a secrets manager returns `{"data": {"credentials": {"username": "...", "password": "..."}}}`, use `$.data.credentials` as the **Data JSONPath**.

| Expression | Meaning |
| --- | --- |
| `$.data.credentials` | Selects the `credentials` object inside `data`. |
| `$.data.*` or `$.data[*]` | Selects the members of an object or the elements of an array. These are wildcard expressions. |
| `$.data[:]` or `$.data[::]` | Selects elements only when `data` is an array. These expressions do not select object members. |
| `$.data['*']` or `$.data["*"]` | Selects a field whose name is literally `*`. The quoted asterisk is not a wildcard. |

Older saved expressions may have used `[:]`, `[::]`, or a quoted asterisk to select object members. Qualytics adjusts those saved paths during the platform upgrade to preserve their selection. Update copies kept in connection templates or scripts before reusing them.

## Referencing the Secret

Type `${key}` in a text or file field under **Connection Properties** or **Authentication**, where `key` is a name inside the secret. The **Type** selector and the **Port** field take no reference: the type is checked against its allowed values and the port must be a number before any secret is read, so a reference in either makes the test or save fail. For a secret holding `username` and `password`, the **Username** field is `${username}` and the **Password** field is `${password}`.

- The syntax is a dollar sign with braces. `$.username` is JSONPath, not a reference, and is sent to the target system as literal text.
- Key names are case sensitive and must match the secret exactly.
- A key name must start with a letter or underscore and contain only letters, digits, and underscores. A key such as `service-account` cannot be referenced even though Vault accepts it. In a file field, in **Private Key Password**, or in the Hive **Client Principal**, `${service-account}` is rejected when you save or test, with a message saying that secret token names may only contain letters, digits, and underscores. In any other field it is left in place as literal text and reaches the data source unchanged, so the failure shows up there as a login error. Name the key `service_account` instead.
- A field can mix literal text and references, for example `jdbc:postgresql://${host}:5432/app`.
- Substitution applies to the connection's own fields. The six Secrets Management fields are used as typed.

### File fields

A file field can hold a reference too, so a file kept in your secrets manager never has to be uploaded. Every connection file field takes one: the Hive Native and Hive **Keytab** and **krb5.conf**, the BigQuery and Google Cloud Storage **Service Account Key**, and the Snowflake **Private Key**.

- Click **Type a value instead**  next to the file field to switch it from an upload to a text box, and enter `${key}`, where `key` holds the file's contents. **Upload a file instead**  switches back, and each mode keeps its own value while you switch.
- A **Keytab** is a binary file. An upload encodes it for you, but a reference is used as stored, so store the keytab in your secrets manager as its base64 form. The text files, such as krb5.conf and a service account key, are stored as they are.
- On a secret field the typed value is masked as a single line, with the usual eye toggle to reveal it.
- A connection saved with a reference reopens with the reference visible in the text box, so you can see which key it points at. A field whose value is never returned, such as a service account key, shows as a saved secret instead.
- A reference that cannot be resolved is rejected when you save, with the keys the secret does hold listed in the message. A reference on a connection with no secrets manager set up is rejected the same way.
- A Snowflake private key may be stored as the key text or as its base64 form. An encrypted private key supplied by reference is not accepted, because its passphrase is never stored. For an uploaded encrypted key, **Private Key Password** can be a `${key}` reference on its own: Qualytics resolves it and decrypts the key before saving.
- A BigQuery service account key by reference is read each time the connection is used, so a key changed in the secrets manager takes effect on the next operation.

## Namespaces

On Vault Enterprise and HCP Vault every mount, role, policy, and secret lives inside a namespace. Qualytics sends no namespace header, so the namespace must be part of both URL paths, right after `/v1/`.

- Secret in namespace `team-a`: `https://vault.example.com/v1/team-a/secret/data/qualytics/postgres`
- AppRole enabled in namespace `team-a`: `https://vault.example.com/v1/team-a/auth/approle/login`
- AppRole enabled in the root namespace: `https://vault.example.com/v1/auth/approle/login`, and its policy must then name the secret path with the namespace prefix, `team-a/secret/data/qualytics/postgres`

To see which namespace a role is in, open **Access** in the Vault UI with the namespace selector set to the namespace in question. If `approle/` is listed there, that namespace belongs in the Login URL. The **Paths** tab of a secret already includes the namespace in the API path it shows.

> **Warning: A missing namespace does not look like a namespace problem**
>
> Logging in against the wrong namespace returns `invalid role or secret ID`, the same message as a wrong secret ID, because Vault does not reveal whether a role exists. Check the namespace before minting new credentials.

## Network Requirements

Qualytics must reach Vault over HTTPS from the addresses shown in the banner below every connection form; see [Finding the addresses to allow](https://userguide.qualytics.io/source-datastore/datastore/connection/how-it-works/#finding-the-addresses-to-allow). Two things to confirm with your network team:

- The firewall allows those addresses to reach Vault's host and port: 443 for most installations, 8200 for a default standalone one.
- Vault's hostname resolves from inside the Qualytics deployment. A name that only resolves on an office network, or a `.local` name, often does not.

A connection test that waits about two minutes and then fails with a gateway timeout is a timeout for the whole request, which includes reaching Vault, reading the secret, and then connecting to the data source. When the timeout happens before Vault has answered, the form values have not been evaluated yet, so changing them does not help until the network path exists. [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/troubleshooting/#the-test-waits-about-two-minutes-and-fails-with-a-gateway-timeout) explains how to tell which stage stalled.

*Last updated: November 9, 2026.*
