# Prepare Vault for a Qualytics Connection

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

This page walks through the Vault-side setup for a connection that uses **Secrets Management**: storing the secret, granting a role read access to it, and producing the credentials Qualytics will log in with. It uses the Vault CLI with the KV secrets engine and AppRole authentication; the same can be done in the Vault web UI.

> **Tip: Already prepared?**
>
> If the secret, policy, and role exist, go to [Configure the Connection](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/how-tos/configure-connection/).

> **Note: Namespaces**
>
> If your Vault uses namespaces (Vault Enterprise and HCP Vault), run every command below with `-namespace=<name>` or export `VAULT_NAMESPACE` first. Note the namespace: it goes into both URLs when you configure the connection. See [How It Works](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/how-it-works/#namespaces).

## Steps

**Step 1**: Confirm the secrets engine. The commands below assume a KV version 2 engine mounted at `secret/`. Check what is mounted, and enable one if it is missing (this needs a Vault administrator):

```bash
vault secrets list -detailed
```

```bash
vault secrets enable -path=secret -version=2 kv
```

The `Options` column of the listing shows `map[version:2]` for a KV version 2 mount. If your mount is KV version 1, drop the `/data/` segment from the policy path and the Secret URL in the later steps, and use `$.data` as the Data JSONPath.

**Step 2**: Store the secret. Choose key names you will reference from the connection form, such as `username` and `password` for a database, or `access_key` and `secret_key` for object storage. A key name must start with a letter or underscore and contain only letters, digits, and underscores, because that is what `${key}` can reference; `service-account` cannot be referenced, `service_account` can.

```bash
vault kv put -mount=secret qualytics/postgres username="app_user" password="s3cr3t"
```

In the Vault UI, open the secret and note the **API path** on its **Paths** tab, for example `/v1/secret/data/qualytics/postgres`. This becomes the end of the **Secret URL**.

**Step 3**: Write a policy that can read the secret. Without it the login succeeds and the fetch is refused with `permission denied`.

```hcl
path "secret/data/qualytics/postgres" {
  capabilities = ["read"]
}
```

```bash
vault policy write qualytics-read qualytics-read.hcl
```

Write the path as the API path without the leading `/v1/` and without the namespace, because a policy is already scoped to the namespace it is written in. KV version 2 paths carry the `/data/` segment; KV version 1 paths do not.

**Step 4**: Enable AppRole, if it is not already enabled.

```bash
vault auth enable approle
```

**Step 5**: Create a role that carries the policy. Qualytics logs in fresh on every connection, so a short token lifetime is fine. The secret ID is different: Qualytics reuses the one saved in the **Credentials Payload** on every login, so it must stay valid for as long as the connection is in use.

```bash
vault write auth/approle/role/qualytics token_policies="qualytics-read" token_ttl=20m token_max_ttl=30m secret_id_ttl=0 secret_id_num_uses=0
```

`secret_id_ttl=0` and `secret_id_num_uses=0` mean the secret ID neither expires nor runs out of uses. If your security policy requires a limited lifetime, set `secret_id_ttl` accordingly and plan the rotation: mint a new secret ID before the old one expires and update the **Credentials Payload** on the connection. An expired or spent secret ID fails every later operation on the connection with `invalid role or secret ID`.

**Step 6**: Read the role ID and mint a secret ID. Keep both private; they go into the **Credentials Payload** only.

```bash
vault read -field=role_id auth/approle/role/qualytics/role-id
```

```bash
vault write -f -field=secret_id auth/approle/role/qualytics/secret-id
```

**Step 7**: Verify the chain before touching Qualytics. Log in as the role, then read the secret with the token it returns.

```bash
vault write -field=token auth/approle/login role_id="<role_id>" secret_id="<secret_id>"
```

```bash
VAULT_TOKEN="<token from above>" vault kv get -mount=secret qualytics/postgres
```

If the second command prints the key/value pairs, Vault is ready. The only remaining questions are whether Qualytics can reach Vault over the network and whether the form values are right, both covered in [Configure the Connection](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/how-tos/configure-connection/).

*Last updated: October 7, 2026.*
