api

github.com/hashicorp/vault/api is the public Go SDK for talking to a Vault server. It's what the vault CLI uses internally and what most Go applications integrating with Vault import. Source: api/ (with its own go.mod).

Purpose

• Provide a high-level, typed client for Vault's HTTP API.
• Expose typed wrappers for every sys/... subsystem Vault offers.
• Handle retries, namespaces, response wrapping, lifetime watching, and HCP authentication.

Directory layout

api/
├── client.go                 # api.Client — the entry point, 56k lines
├── logical.go                # Read/Write/Delete/List + Logical()
├── auth.go, auth_token.go    # Auth() helpers
├── auth/                     # Per-auth-method packages (their own go modules)
│   ├── approle/
│   ├── aws/
│   ├── azure/
│   ├── gcp/
│   ├── kubernetes/
│   ├── ldap/
│   ├── userpass/
│   └── ...
├── kv.go, kv_v1.go, kv_v2.go # KV typed helpers
├── sys.go                    # Sys() entry; one file per subsystem below
├── sys_audit.go              # vault audit … (enable/disable/list)
├── sys_auth.go               # vault auth …
├── sys_capabilities.go       # vault token capabilities
├── sys_config_cors.go
├── sys_generate_root.go
├── sys_hastatus.go, sys_health.go
├── sys_init.go, sys_seal.go, sys_rekey.go, sys_stepdown.go
├── sys_leases.go             # vault lease …
├── sys_leader.go
├── sys_mfa.go, sys_monitor.go
├── sys_mounts.go             # vault secrets … (enable/list/tune)
├── sys_plugins.go, sys_plugins_runtimes.go
├── sys_policy.go
├── sys_raft.go               # vault operator raft …
├── sys_rotate.go
├── sys_billing.go, sys_reporting_scan.go, sys_utilization_report.go
├── sys_ui_custom_message.go
├── output_policy.go, output_string.go, replication_status.go, secret.go
├── plugin_helpers.go, plugin_runtime_types.go, plugin_types.go
├── lifetime_watcher.go       # auto-renew long-running tokens / leases
├── ssh.go, ssh_agent.go
├── cliconfig/                # ~/.vault config parsing
├── tokenhelper/              # external token helper protocol
└── help.go, hcl_dup_attr_deprecation.go, sudo_paths.go, request.go, response.go

Key abstractions

Symbol	File	Description
Client	api/client.go	The main type: address, token, retries, namespaces, transport.
Client.Logical()	api/logical.go	Read/Write/Delete/List + KV v1/v2 helpers.
Client.Sys()	api/sys.go and siblings	Bindings for every sys/... endpoint.
Client.Auth()	api/auth.go	Token-less login helpers used by per-method packages.
Client.SetNamespace, WithNamespace	api/client.go	Per-call namespace override.
LifetimeWatcher	api/lifetime_watcher.go	Auto-renew a long-running token or lease, fanning out events.
Secret, Auth, SecretAuth, SecretWrapInfo	api/secret.go	Response types.

Per-auth-method packages

Each api/auth/<name>/ subdirectory is its own Go module so callers can import only what they need without dragging in the full Vault binary. They expose methods like:

import "github.com/hashicorp/vault/api/auth/approle"

method, _ := approle.NewAppRoleAuth(roleID, &approle.SecretID{FromString: secretID})
authInfo, err := client.Auth().Login(ctx, method)

Currently versioned per-auth-method modules: approle, aws, azure, gcp, kubernetes, ldap, userpass.

CLI integration

The vault CLI uses api.Client for every operation. command/base.go wires up an api.Client factory from common flags (-address, -token, -tls-…, -namespace). api/cliconfig/ parses ~/.vault for default flag values.

Lifetime watching

secret, _ := client.Logical().Write("auth/approle/login", data)
watcher, _ := client.NewLifetimeWatcher(&api.LifetimeWatcherInput{Secret: secret})
go watcher.Start()
defer watcher.Stop()
for {
    select {
    case err := <-watcher.DoneCh():
        return err
    case <-watcher.RenewCh():
        // renewed
    }
}

This is the canonical way to keep a token alive in a long-running process. Vault Agent uses the same machinery internally.

Integration points

• command/ (the CLI) is the largest single user.
• command/agent and command/proxy use api.Client and the per-method packages for auto-auth.
• External Go projects integrate Vault by importing api/.

Entry points for modification

• Add a new sys/... endpoint binding: create api/sys_<thing>.go, expose a method on Client.Sys().
• Add a new auth method helper package: create api/auth/<name>/, ship as its own go module via go.mod.
• Tweak retry behavior: api/client.go's Config struct has MinRetryWait, MaxRetryWait, MaxRetries, Backoff.