How-To Guide

How to Use HashiCorp Vault for Secrets Management

Enterprise-grade secrets management for growing applications

TL;DR

TL;DR (30 minutes): Install Vault, start the server in dev mode to learn, then store secrets with vault kv put . Access them in your app via the Vault API or SDK. For production, run Vault in HA mode with proper unsealing and access policies.

Prerequisites:

Command line access
Basic understanding of environment variables
Docker installed (optional, for easier setup)

Why This Matters

As your application grows, managing secrets in environment variables becomes unwieldy. HashiCorp Vault provides centralized secrets management with encryption, access control, audit logging, and automatic rotation. It's the industry standard for organizations handling sensitive data.

Vault helps you avoid common problems: secrets sprawled across multiple .env files, no audit trail of who accessed what, and painful manual rotation when credentials are compromised.

Step-by-Step Guide

Install HashiCorp Vault

Download and install Vault for your platform:

# macOS with Homebrew
brew tap hashicorp/tap
brew install hashicorp/tap/vault

# Ubuntu/Debian
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vault

# Or use Docker
docker pull hashicorp/vault

Verify the installation:

vault --version

Start Vault in development mode

For learning and local development, start Vault in dev mode:

# Start dev server (not for production!)
vault server -dev

# In a new terminal, set the address
export VAULT_ADDR='http://127.0.0.1:8200'

# Dev mode prints a root token - save it
export VAULT_TOKEN='your-root-token-here'

Dev mode automatically unseals Vault and gives you a root token. Never use dev mode in production.

Store your first secret

Use the KV (key-value) secrets engine to store secrets:

# Enable the KV secrets engine (v2 recommended)
vault secrets enable -path=secret kv-v2

# Store a secret
vault kv put secret/myapp/database \
  username="dbuser" \
  password="supersecret123" \
  host="db.example.com"

# Store API keys
vault kv put secret/myapp/api \
  stripe_key="sk_live_xxxxx" \
  openai_key="sk-xxxxx"

Read secrets from Vault

Retrieve secrets using the CLI or API:

# Read via CLI
vault kv get secret/myapp/database

# Get specific field
vault kv get -field=password secret/myapp/database

# Read via API (curl)
curl -H "X-Vault-Token: $VAULT_TOKEN" \
  $VAULT_ADDR/v1/secret/data/myapp/database

Access Vault in your application

Use the Vault SDK in your application:

// Node.js with node-vault
import vault from 'node-vault';

const client = vault({
  apiVersion: 'v1',
  endpoint: process.env.VAULT_ADDR,
  token: process.env.VAULT_TOKEN
});

async function getDbCredentials() {
  const result = await client.read('secret/data/myapp/database');
  return result.data.data; // { username, password, host }
}

// Use in your app
const dbCreds = await getDbCredentials();
const connection = await createConnection({
  host: dbCreds.host,
  user: dbCreds.username,
  password: dbCreds.password
});

Create access policies

Define who can access which secrets:

# Create a policy file: myapp-policy.hcl
path "secret/data/myapp/*" {
  capabilities = ["read"]
}

path "secret/metadata/myapp/*" {
  capabilities = ["list"]
}

# Apply the policy
vault policy write myapp-read myapp-policy.hcl

# Create a token with this policy
vault token create -policy=myapp-read -ttl=24h

Production Considerations:

Never use dev mode in production - use proper storage backend (Consul, PostgreSQL, etc.)
Implement proper unsealing with Shamir's secret sharing or auto-unseal
Use AppRole or Kubernetes auth instead of static tokens
Enable audit logging for compliance
Run Vault in HA mode with multiple nodes

How to Verify It Worked

List secrets: Run vault kv list secret/myapp to see stored secrets
Check access: Create a limited token and verify it can only access allowed paths
Test from app: Your application should successfully retrieve secrets without hardcoding them
Verify audit logs: Check vault audit list and review access logs

# Verify secrets are stored
vault kv list secret/myapp

# Test limited token
VAULT_TOKEN=limited-token vault kv get secret/myapp/database  # Should work
VAULT_TOKEN=limited-token vault kv get secret/other/secrets   # Should fail

Common Errors & Troubleshooting

Error: "Vault is sealed"

Vault requires unsealing after restart. Use vault operator unseal with your unseal keys.

Error: "permission denied"

Your token doesn't have access to this path. Check your policies with vault token lookup.

Error: "connection refused"

Vault server isn't running or VAULT_ADDR is wrong. Verify with vault status.

Error: "path not found"

The secrets engine might not be enabled. Check with vault secrets list.

When should I use Vault vs. simple environment variables?

Use environment variables for small projects with few secrets. Switch to Vault when you need audit logging, secret rotation, multiple environments, or team access control. If you're handling payment data or user credentials at scale, Vault is worth the setup cost.

Is there a managed Vault service?

Yes, HashiCorp offers HCP Vault as a managed service. AWS also has Secrets Manager, and Azure has Key Vault - these are simpler alternatives if you're on those platforms.

How do I rotate secrets in Vault?

Update the secret with vault kv put - Vault maintains version history. For databases, use Vault's dynamic secrets feature to automatically generate and rotate credentials.