> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luumen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HashiCorp Vault integration

> Source host credentials and integration credentials from HashiCorp Vault instead of entering them directly in the Luumen UI.

The agent can pull credentials from a HashiCorp Vault server at runtime, so passwords and keys never need to be stored directly in the Luumen UI. Use Vault when you want credentials to stay in one place, rotate independently of Luumen, or follow a strict no-plaintext-secrets policy.

## When to use Vault

Vault is optional. Direct credentials entered in the UI (encrypted at rest by Luumen) work fine for many environments. Reach for Vault when:

* You already operate Vault and want Luumen to follow the same rotation policy as the rest of your systems.
* Compliance requirements rule out storing credentials in Luumen, even encrypted.
* You want to centralize host credentials and integration credentials in a single location.

## Configure the Vault connection

Vault is enabled and configured from the Luumen UI. You'll provide:

| Setting           | Description                                                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Vault address** | URL of your Vault server (e.g., `https://vault.example.com`).                                                                                                                                        |
| **KV version**    | The KV secrets engine version — `v1` or `v2`. Defaults to `v2`.                                                                                                                                      |
| **Auth method**   | How the agent authenticates to Vault. The simplest option is a token; for production, prefer an auth method that rotates (AppRole, Kubernetes, etc.) configured via environment on the Patch server. |

The Vault token is best provided via the `VAULT_TOKEN` environment variable on the agent service rather than entered in the UI. On systemd, that's `Environment=VAULT_TOKEN=...` in the unit file (or an `EnvironmentFile` reference to a root-only file).

## Reference a secret from a credential field

Once Vault is connected, any credential field in the UI (host password, integration credentials) accepts a Vault reference instead of a literal value. A reference points at a Vault path and the key within that path's data:

* **Path** — for example, `secret/luumen/windev`
* **Key** — for example, `password`

On every agent run, the agent reads the path from Vault and uses the value at the named key. Rotating the secret in Vault rotates the credential in Luumen automatically — no Luumen-side change needed.

## Operational notes

* **Vault must be reachable from the Patch server.** The agent does not cache secrets across runs. If Vault is unreachable during a scheduled run, that run will skip hosts whose credentials it cannot resolve and log the error.
* **Permissions follow Vault's model.** The token (or auth method) you give the agent needs read access to every path referenced from the UI — and only those paths.
* **Rotation is transparent to Luumen.** When you rotate a credential in Vault, the agent picks up the new value on its next run. No agent restart is required.

If you don't already operate Vault and don't have a compliance reason to add it, sticking with credentials entered directly in the UI is usually simpler. Apiphani can help you weigh the tradeoff during white-glove setup.