Vault API

Vault API is the Go client package published from within the HashiCorp Vault repository, giving Go programs a typed way to talk to a running Vault server over its HTTP API. It wraps token and namespace handling, TLS/mTLS configuration, retries, and rate limiting behind a single Client type, then layers on higher-level helpers for reading and writing KV v1/v2 secrets, logging in through any of Vault’s pluggable auth methods (AppRole, AWS, Azure, GCP, Kubernetes, LDAP, userpass, and custom implementations of the AuthMethod interface), and renewing leases automatically via a LifetimeWatcher.

Beyond secrets access, the package exposes a Sys() client for administrative operations — mounting and tuning secrets engines and auth backends, managing policies, checking seal/health/leader status, and inspecting replication state — which is why it doubles as the SDK behind Vault’s own CLI and Terraform provider as well as countless third-party integrations. Because it ships as its own Go module (github.com/hashicorp/vault/api) with an independent go.mod, applications can pin a compatible client version without pulling in the entire Vault server codebase.

The library targets teams building services that need to fetch dynamic secrets, encrypt data via Vault’s transit engine, or authenticate workloads without embedding long-lived credentials — the client’s login flow exchanges auth-method-specific credentials for a short-lived token and can automatically renew it for the life of the process.

What You Get

• A Client type handling TLS/mTLS, namespaces, retries (via go-retryablehttp), rate limiting, and token/MFA header management out of the box
• KV v1 and v2 helpers (KVv1/KVv2) that abstract away the version-specific request shapes for reading, writing, and listing secrets
• Pluggable AuthMethod login support with ready-made implementations for AppRole, AWS, Azure, GCP, Kubernetes, LDAP, and userpass, plus a Login/MFALogin flow that sets the client token automatically
• A LifetimeWatcher for automatic background renewal of tokens and leases so long-running services don’t have to re-authenticate manually
• A Sys() sub-client covering mounts, auth tuning, policies, seal status, health checks, leader status, and replication status for operational tooling
• Sudo-path detection (sudoPaths) that mirrors Vault’s own policy requirements, useful for building safe wrapper tooling around privileged endpoints

Common Use Cases

• Fetching database credentials, API keys, or certificates from Vault at service startup instead of storing them in config
• Authenticating a Kubernetes workload to Vault via the Kubernetes auth method and letting the LifetimeWatcher keep the resulting token alive
• Building internal CLIs or automation scripts that call Vault’s sys/ endpoints for mounting engines, tuning auth backends, or checking cluster health
• Encrypting and decrypting application data through Vault’s transit secrets engine via the generic logical write/read calls
• Powering third-party integrations and Terraform-style tooling that needs the same client Vault’s own CLI uses

Under The Hood

Architecture The module centers on a single Client struct (client.go, ~1900 lines) that owns HTTP transport, address/namespace/token state, and retry/rate-limit configuration, exposing sub-clients — Auth(), Logical(), Sys() — as thin wrappers that share the parent client’s request-building path (request.go, response.go). Secrets flow through a uniform Secret type (secret.go) regardless of which backend produced them, so KV, auth, and sys responses are decoded consistently; the KVv1/KVv2 helpers (kv.go, kv_v1.go, kv_v2.go) and the AuthMethod interface (auth.go) are the two main points where backend-specific logic is layered on top of that generic core. A dedicated LifetimeWatcher (lifetime_watcher.go) runs independently to renew secrets/tokens on a timer, decoupling renewal from the request/response path entirely.

Tech Stack Pure Go, published as its own module (go.mod pinned to a recent Go toolchain) so it can be versioned independently of the Vault server binary. Dependencies are deliberately minimal for a client library: go-retryablehttp and go-cleanhttp for transport, go-rootcerts for TLS trust configuration, hashicorp/go-hclog for optional logging, mapstructure for decoding generic secret payloads into typed structs, and golang.org/x/time/rate for client-side rate limiting. Auth-method subpackages (auth/aws, auth/kubernetes, etc.) each carry their own go.mod, keeping cloud-provider SDK dependencies out of the core module for consumers who only need one method.

Code Quality Extensive test coverage — roughly twenty _test.go files alongside their corresponding implementation files, including property-based tests (testing/quick) for the renewer — plus golangci-lint configuration and dedicated CI workflows (ci.yml, code-checker.yml, benchmark-prevent-performance-degradations.yml) run against the monorepo on every change. Errors are returned explicitly and wrapped with context (fmt.Errorf("...: %w", err)) rather than swallowed, and public APIs favor named struct fields over positional parameters for readability.

API Design The client reads as a deliberately layered SDK: a generic Logical() read/write escape hatch exists for any endpoint, while KV, auth, and sys operations get purpose-built, discoverable methods on their own sub-clients so callers rarely need to hand-construct paths. Getting started requires only api.NewClient(config) and a token or AuthMethod, and consistent context-aware method variants (...WithContext) are provided throughout for cancellation and timeouts — a low-boilerplate surface for a client covering this much of Vault’s API.