HashiCorp Vault API

Vault exposes a unified HTTP API for all secrets engines and auth methods.

Overview

Base URL

https://vault-01.inside.domusdigitalis.dev:8200/v1/

Auth

Token, AppRole, LDAP, OIDC

Format

JSON

CLI

vault command wraps API

Key Paths

Engine Path Purpose

KV Secrets

kv/data/{path}

Key-value secrets storage

PKI

pki_int/issue/{role}

Certificate issuance

SSH CA

ssh/sign/{role}

SSH certificate signing

Auth

auth/{method}/login

Authentication

Sys

sys/

System operations

Examples

Read KV Secret

# CLI
vault kv get kv/infrastructure/ise

# curl
curl -ks -H "X-Vault-Token: $VAULT_TOKEN" \
  "$VAULT_ADDR/v1/kv/data/infrastructure/ise" | jq '.data.data'

Write KV Secret

# CLI
vault kv put kv/infrastructure/newservice \
  username="admin" \
  password="secret123"

# curl
curl -ks -H "X-Vault-Token: $VAULT_TOKEN" \
  -X POST "$VAULT_ADDR/v1/kv/data/infrastructure/newservice" \
  -d '{"data": {"username": "admin", "password": "secret123"}}' | jq

Issue Certificate

# CLI
vault write pki_int/issue/domus-client \
  common_name="host.inside.domusdigitalis.dev" \
  ttl=8760h

# curl
curl -ks -H "X-Vault-Token: $VAULT_TOKEN" \
  -X POST "$VAULT_ADDR/v1/pki_int/issue/domus-client" \
  -d '{"common_name": "host.inside.domusdigitalis.dev", "ttl": "8760h"}' | jq

Sign SSH Key

# CLI
vault write -field=signed_key ssh/sign/domus-client \
  public_key=@~/.ssh/id_ed25519_vault.pub \
  valid_principals="evanusmodestus,admin,root"

# curl
curl -ks -H "X-Vault-Token: $VAULT_TOKEN" \
  -X POST "$VAULT_ADDR/v1/ssh/sign/domus-client" \
  -d "{\"public_key\": \"$(cat ~/.ssh/id_ed25519_vault.pub)\", \"valid_principals\": \"evanusmodestus,admin,root\"}" \
  | jq -r '.data.signed_key'

AppRole Login

curl -ks -X POST "$VAULT_ADDR/v1/auth/approle/login" \
  -d "{\"role_id\": \"$ROLE_ID\", \"secret_id\": \"$SECRET_ID\"}" \
  | jq -r '.auth.client_token'

Environment Setup

# Load from dsec
dsource d000 dev/app

# Or manually
export VAULT_ADDR="https://vault-01.inside.domusdigitalis.dev:8200"
export VAULT_TOKEN="<from vault login or approle>"

Learnings

Vault API Gotchas

  • KV v2 path is kv/data/{path} not kv/{path} (API adds /data/)

  • CLI vault kv get handles this automatically

  • Token must have appropriate policy for the path

  • SSH signing requires valid_principals on every request (role defaults are ignored)

  • AppRole returns token in .auth.client_token