Vault API

Overview

Vault exposes a RESTful JSON API on port 8200. All requests include X-Vault-Token header for authenticated endpoints. Unauthenticated endpoints (health, init) need no token.

Base URL: http://vault.vault:8200 (in-cluster) or https://vault.kubexa.tech (external via Gateway).

API Endpoints

System

Health status codes:

Auth (Kubernetes)

# Login with K8s SA token
SA_JWT=$(kubectl create token my-sa -n my-ns)
curl -s http://vault.vault:8200/v1/auth/kubernetes/login \
  -d "{\"role\":\"my-role\",\"jwt\":\"$SA_JWT\"}"
# Returns: {"auth":{"client_token":"hvs...","policies":["my-policy"]}}

KV Secrets (v2)

# Write a secret
curl -s http://vault.vault:8200/v1/secret/data/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"data":{"password":"s3cret!"}}'

# Read a secret
curl -s http://vault.vault:8200/v1/secret/data/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN"
# Returns: {"data":{"data":{"password":"s3cret!"},"metadata":{...}}}

# List secrets at a path
curl -s http://vault.vault:8200/v1/secret/metadata/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  | jq '.data.keys'

KV Secrets (v1)

Policies

# Create read-only policy for myapp
curl -s http://vault.vault:8200/v1/sys/policies/acl/myapp \
  -X PUT \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"policy":"path \"secret/data/myapp/*\" {capabilities=[\"read\",\"list\"]}"}'

Token

Auth Methods

Secrets Engines

Raft

# Join Raft cluster
curl -s http://127.0.0.1:8200/v1/sys/storage/raft/join \
  -X POST \
  -d '{"leader_api_addr":"http://vault-0.vault-internal:8200"}'

# Take snapshot
curl -s http://vault.vault:8200/v1/sys/storage/raft/snapshot \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -o vault-snapshot.snap

Auth Methods Summary

Health Check Examples

# Quick health
curl -s http://vault.vault:8200/v1/sys/health | jq .initialized

# Detailed status
curl -s http://vault.vault:8200/v1/sys/seal-status | jq '.sealed, .t, .n, .progress'

Common Mistakes

• KV v2 path includes data/ prefix. For KV v2 engine mounted at secret, the read path is /v1/secret/data/myapp, not /v1/secret/myapp. The latter returns a 404.
• Health endpoint returns non-200 for sealed/standby. A 503 (sealed) is NOT an error — it's expected after restart. Check initialized and sealed fields in the response body, not the HTTP status alone.
• Token in URL is stripped by proxies. Use X-Vault-Token header, not ?token= query param. Proxies and load balancers may log or strip query params.
• Kubernetes auth needs SA token with right audience. The vault audience must be configured in the SA or the default token may not be accepted. Use kubectl create token with --audience=vault for explicit audience.
• list capabilities for metadata listing. Reading /v1/secret/metadata/ (to list keys) requires list capability at that path, not read. Without it, the response is empty.
• Raft join after unseal. A sealed node cannot join the Raft cluster. Always unseal before raft join. The joining node will sync data from the leader.
• Snapshot restore requires same cluster size. Raft snapshots can only be restored to a cluster with the same number of peers. Adding/removing nodes after restore may fail.