Vault API Skill | Agent Skills

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

| Method | Endpoint | Description | Auth | |--------|----------|-------------|------| | GET | /v1/sys/health | Cluster health (see status codes below) | No | | GET | /v1/sys/seal-status | Seal status | No | | PUT | /v1/sys/init | Initialize cluster | No | | PUT | /v1/sys/unseal | Unseal (submit key share) | No | | GET | /v1/sys/leader | Current leader info | No |

Health status codes:

| Code | Meaning | |------|---------| | 200 | Active, unsealed | | 429 | Standby, unsealed | | 472 | Disaster Recovery secondary (enterprise) | | 473 | Performance standby (enterprise) | | 501 | Not initialized | | 503 | Sealed |

Auth (Kubernetes)

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /v1/auth/kubernetes/login | Login with service account JWT |

# 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)

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/{mount}/data/{path} | Read secret | | PUT | /v1/{mount}/data/{path} | Create/update secret | | DELETE | /v1/{mount}/data/{path} | Delete latest version | | GET | /v1/{mount}/metadata/{path} | Read metadata (versions, timestamps) | | POST | /v1/{mount}/delete/{path} | Delete all versions | | POST | /v1/{mount}/undelete/{path} | Undelete |

# 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)

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/{mount}/{path} | Read secret | | PUT | /v1/{mount}/{path} | Create/update secret | | DELETE | /v1/{mount}/{path} | Delete secret |

Policies

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/sys/policies/acl | List ACL policies | | GET | /v1/sys/policies/acl/{name} | Read policy | | PUT | /v1/sys/policies/acl/{name} | Create/update policy | | DELETE | /v1/sys/policies/acl/{name} | Delete policy |

# 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

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /v1/auth/token/create | Create token | | POST | /v1/auth/token/create-orphan | Create orphan token | | GET | /v1/auth/token/lookup-self | Validate/lookup own token | | POST | /v1/auth/token/renew-self | Renew own token | | POST | /v1/auth/token/revoke-self | Revoke own token |

Auth Methods

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/sys/auth | List enabled auth methods | | POST | /v1/sys/auth/{type} | Enable auth method | | DELETE | /v1/sys/auth/{path} | Disable auth method |

Secrets Engines

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/sys/mounts | List enabled secret engines | | POST | /v1/sys/mounts/{path} | Enable secret engine (type: kv-v2, kv, transit, etc.) | | DELETE | /v1/sys/mounts/{path} | Disable/delete secret engine |

Raft

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /v1/sys/storage/raft/join | Join Raft cluster | | GET | /v1/sys/storage/raft/configuration | List Raft peers | | POST | /v1/sys/storage/raft/snapshot | Take Raft snapshot |

# 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

| Method | Endpoint Mount | Use Case | |--------|---------------|----------| | Kubernetes | /v1/auth/kubernetes/login | In-cluster pods via SA JWT | | Token | /v1/auth/token/create | Root token, periodic tokens | | AppRole | /v1/auth/approle/login | Machine-to-machine (w/ secretId) | | Userpass | /v1/auth/userpass/login | Human users | | LDAP | /v1/auth/ldap/login | Enterprise directory integration | | JWT/OIDC | /v1/auth/jwt/login | External OIDC providers | | Cert | /v1/auth/cert/login | mTLS client certificates |

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.

Agent Skills: Vault API

Install this agent skill to your local

Skill Files