Configuring Vaults¶

A vault is a credentials storage system where secrets are stored. This guide covers how to configure different vault types.

Note: All vault configuration is managed via the Web UI (Vaults Config) or the admin API (POST /api/config/vaults, PUT /api/config/vaults/{vault_id}). The API accepts and returns JSON. The YAML-style snippets in this guide are schema reference only — the field names map 1:1 to the JSON keys used by the API.

Supported Vault Types¶

Azure Key Vault - Microsoft's cloud secrets management
Bitwarden - Open-source password manager (Bitwarden Cloud)
Vaultwarden - Self-hosted Bitwarden-compatible server
HashiCorp Vault - Enterprise secrets management
AWS Secrets Manager - AWS managed secrets (HTTP adapter)
Keeper Secrets Manager - Keeper enterprise secrets
Generic REST API - Custom HTTP-based vaults
Tool Backend - CLI-backed vaults (type tool)

Azure Key Vault¶

Azure Key Vault is Microsoft's cloud service for securely storing and managing secrets.

Basic Configuration¶

vaults:
  - id: azure-prod
    name: "Azure Key Vault - Production"
    type: azure
    endpoint: "https://myprodvault.vault.azure.net/secrets"
    auth:
      method: bearer
      headers:
        token: "${AZURE_ACCESS_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"

Notes¶

The adapter expects a bearer token. Obtain it via Azure AD (CLI, managed identity, or service principal) and provide it as auth.headers.token.
If your endpoint does not include api-version, the client appends api-version=7.4 by default. Override with operations_override if needed.

Optional Overrides¶

vaults:
  - id: azure-prod
    type: azure
    endpoint: "https://myprodvault.vault.azure.net/secrets"
    auth:
      method: bearer
      headers:
        token: "${AZURE_ACCESS_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"
    operations_override:
      list:
        endpoint: "https://myprodvault.vault.azure.net/secrets?api-version=7.4"
        response:
          path: "value"
          name_field: "name"
      get:
        endpoint: "https://myprodvault.vault.azure.net/secrets/{name}?api-version=7.4"
        response:
          value_path: "value"

Bitwarden¶

Bitwarden is a cloud-hosted password manager with a modern API. Use type: bitwarden for Bitwarden Cloud or self-hosted Bitwarden Server.

Basic Configuration¶

vaults:
  - id: bitwarden-prod
    name: "Bitwarden - Production"
    type: bitwarden
    endpoint: "https://api.bitwarden.com/ciphers"
    method: POST
    auth:
      method: oauth2
      oauth:
        client_id: "${BITWARDEN_CLIENT_ID}"
        client_secret: "${BITWARDEN_CLIENT_SECRET}"
        scope: api
    field_names:
      name_field: "name"
      value_field: "login"

Bitwarden Cloud: use https://api.bitwarden.com/ciphers as the endpoint. The OAuth token endpoint defaults to https://identity.bitwarden.com/connect/token.

Vaultwarden¶

Vaultwarden is a self-hosted, Bitwarden-compatible server. Use type: vaultwarden for Vaultwarden instances.

Basic Configuration¶

vaults:
  - id: vaultwarden-prod
    name: "Vaultwarden - Production"
    type: vaultwarden
    endpoint: "https://vault.example.com/api/ciphers"
    method: POST
    auth:
      method: oauth2
      oauth:
        token_endpoint: "https://vault.example.com/identity/connect/token"
        client_id: "${VW_CLIENT_ID}"
        client_secret: "${VW_CLIENT_SECRET}"
        scope: api
        extra_params:
          deviceIdentifier: "sync-daemon"
          deviceType: "14"
          deviceName: "Sync Daemon"
    field_names:
      name_field: "name"
      value_field: "login"

Connection Options¶

Option	Type	Required	Description
`id`	string	Yes	Unique identifier
`name`	string	No	Human-readable name
`type`	string	Yes	Must be `bitwarden` or `vaultwarden`
`endpoint`	string	Yes	Ciphers API endpoint
`method`	string	No	HTTP method for write operations (`POST` or `PUT`, default `PUT`)
`auth`	object	Yes	Authentication config
`field_names`	object	Yes	Maps `name_field` and `value_field`

Keeper Secrets Manager¶

Keeper provides a JSON API for secrets. Use operations overrides to map list/get/set/delete paths.

vaults:
  - id: keeper
    type: keeper
    endpoint: "https://keeper.example.com/api/secrets"
    auth:
      method: bearer
      headers:
        token: "${KEEPER_TOKEN}"
    field_names:
      name_field: "title"
      value_field: "data"
    operations_override:
      list:
        endpoint: "https://keeper.example.com/api/secrets"
        response:
          path: "records"
          name_field: "title"
      get:
        endpoint: "https://keeper.example.com/api/secrets/{name}"
        response:
          value_path: "data"
      set:
        endpoint: "https://keeper.example.com/api/secrets/{name}"
        method: PUT
      delete:
        endpoint: "https://keeper.example.com/api/secrets/{name}"
        method: DELETE

HashiCorp Vault¶

HashiCorp Vault is an enterprise secrets management solution.

Basic Configuration¶

vaults:
  - id: hashicorp-prod
    name: "HashiCorp Vault - Production"
    type: vault
    endpoint: "https://vault.example.com:8200/v1/secret/data"
    auth:
      method: custom
      headers:
        X-Vault-Token: "${VAULT_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"

Notes¶

The generic adapter expects Vault KV v2 semantics (list via metadata, read/write via data).
If you authenticate with AppRole/Kubernetes, exchange credentials for a token externally and pass it in X-Vault-Token.

AWS Secrets Manager¶

AWS managed secrets service integrated with IAM.

Notes¶

The generic adapter does not implement AWS Signature V4 signing, which is required for direct calls to the AWS Secrets Manager API. Use the Tool Backend (type tool) with the AWS CLI for full AWS Secrets Manager integration, or use a pre-authenticated proxy that handles SigV4 signing.

Tool Backend (Recommended)¶

See Tool Backend for an example of using the AWS CLI as the vault backend. This is the recommended approach for AWS Secrets Manager.

Pre-authenticated Proxy¶

If you operate a proxy that handles AWS SigV4 signing on your behalf, configure it as a generic vault:

{
  "id": "aws-prod",
  "name": "AWS Secrets Manager (via proxy)",
  "type": "aws",
  "endpoint": "https://my-sigv4-proxy.internal/secretsmanager",
  "auth": {
    "method": "bearer",
    "headers": {"token": "${PROXY_TOKEN}"}
  },
  "field_names": {"name_field": "Name", "value_field": "SecretString"}
}

Generic REST API¶

Configure any HTTP-based vault system with REST API:

Basic Configuration¶

vaults:
  - id: generic-api
    name: "Generic REST API"
    type: generic
    endpoint: "https://secrets.example.com"
    auth:
      method: bearer
      headers:
        token: "${API_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"

Authentication Methods¶

Bearer Token¶

vaults:
  - id: rest-bearer
    type: generic
    endpoint: "https://api.example.com"
    auth:
      method: bearer
      headers:
        token: "${API_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"

Basic Authentication¶

vaults:
  - id: rest-basic
    type: generic
    endpoint: "https://api.example.com"
    auth:
      method: basic
      headers:
        username: "${API_USER}"
        password: "${API_PASSWORD}"
    field_names:
      name_field: "name"
      value_field: "value"

API Key (Header)¶

vaults:
  - id: rest-apikey
    type: generic
    endpoint: "https://api.example.com"
    auth:
      method: api_key
      headers:
        api_key: "${API_KEY}"
    field_names:
      name_field: "name"
      value_field: "value"

OAuth2¶

vaults:
  - id: rest-oauth2
    type: generic
    endpoint: "https://api.example.com"
    auth:
      method: oauth2
      oauth:
        token_endpoint: "https://auth.example.com/token"
        client_id: "${CLIENT_ID}"
        client_secret: "${CLIENT_SECRET}"
        scope: "api"
    field_names:
      name_field: "name"
      value_field: "value"

Custom API Configuration¶

vaults:
  - id: rest-custom
    type: generic
    endpoint: "https://api.example.com"
    auth:
      method: bearer
      headers:
        token: "${API_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"
    operations_override:
      list:
        endpoint: "https://api.example.com/v1/secrets"
        response:
          path: "data"
          name_field: "name"
      get:
        endpoint: "https://api.example.com/v1/secrets/{name}"
        response:
          value_path: "value"
      set:
        endpoint: "https://api.example.com/v1/secrets/{name}"
        method: PUT
      delete:
        endpoint: "https://api.example.com/v1/secrets/{name}"
        method: DELETE

Multiple Vaults of Same Type¶

You can configure multiple vaults of the same type:

vaults:
  - id: akv-prod
    type: azure
    endpoint: "https://prod.vault.azure.net/secrets"
    auth:
      method: bearer
      headers:
        token: "${AZURE_ACCESS_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"

  - id: akv-staging
    type: azure
    endpoint: "https://staging.vault.azure.net/secrets"
    auth:
      method: bearer
      headers:
        token: "${AZURE_ACCESS_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"

  - id: akv-dev
    type: azure
    endpoint: "https://dev.vault.azure.net/secrets"
    auth:
      method: bearer
      headers:
        token: "${AZURE_ACCESS_TOKEN}"
    field_names:
      name_field: "name"
      value_field: "value"

Vault Connectivity¶

The daemon lists all configured vaults via GET /api/vaults (authenticated). To verify connectivity, trigger a sync manually via POST /api/syncs/{sync_id}/execute and observe the results in the run history.

Common Issues¶

Connection Timeout¶

Problem: Vault not reachable

Solutions: - Verify endpoint URL - Check network connectivity - Verify firewall rules - Check DNS resolution

Authentication Failed¶

Problem: Wrong credentials or permissions

Solutions: - Verify credentials - Check credential expiration - Verify required permissions - Check managed identity is enabled

SSL Certificate Error¶

Problem: TLS verification fails

Solutions: - Verify certificate is valid - Update system certificates - For development only: use skip_ssl_verify: true

Best Practices¶

✅ Do: - Use managed identities on cloud platforms - Store sensitive values in environment variables - Verify connectivity during startup - Enable audit logging - Use least-privilege permissions - Rotate credentials regularly

❌ Don't: - Hardcode credentials in configuration files - Use skip_ssl_verify: true in production - Share configuration files with secrets - Use overly permissive credentials - Forget to test backup/restore procedures

Configuring Vaults¶

Supported Vault Types¶

Azure Key Vault¶

Basic Configuration¶

Notes¶

Optional Overrides¶

Bitwarden¶

Basic Configuration¶

Vaultwarden¶

Basic Configuration¶

Connection Options¶

Keeper Secrets Manager¶

HashiCorp Vault¶

Basic Configuration¶

Notes¶

AWS Secrets Manager¶

Notes¶

Tool Backend (Recommended)¶

Pre-authenticated Proxy¶

Generic REST API¶

Basic Configuration¶

Authentication Methods¶

Bearer Token¶

Basic Authentication¶

API Key (Header)¶

OAuth2¶

Custom API Configuration¶

Multiple Vaults of Same Type¶

Vault Connectivity¶

Common Issues¶

Connection Timeout¶

Authentication Failed¶

SSL Certificate Error¶

Best Practices¶

Next Steps¶