hashicorp/vault

API

Vault's wire protocol is a JSON-over-HTTPS REST API on a single port (default 8200). It's prefixed with /v1/ and organized by mount path: /v1/auth/<method>/... for auth backends, /v1/<secret-mount>/... for secret engines, /v1/sys/... for the in-process system backend.

This page is a contributor-facing summary of the wire surface. The user-facing reference is at https://developer.hashicorp.com/vault/api-docs.

Versioning

The API version is v1. There has never been a /v2/ and there's no plan to add one — backwards-incompatible changes are guarded by feature flags and capability checks rather than path-level versioning.

The OpenAPI 3 specification is generated at runtime from the framework backends:

vault read sys/internal/specs/openapi

The generation logic is in sdk/framework/openapi.go (46k lines of reflective handling).

Major endpoint groups

Authentication endpoints

POST /v1/auth/<mount>/login — exchange credentials for a token. The exact body depends on the method.
POST /v1/auth/token/create, /v1/auth/token/lookup, /v1/auth/token/renew, /v1/auth/token/revoke, /v1/auth/token/capabilities.
POST /v1/sys/mfa/validate — submit MFA factors during a multi-step login.

Secret engine endpoints

GET /v1/<mount>/<path> — read.
LIST /v1/<mount>/<path> (or GET ?list=true) — list children.
POST /v1/<mount>/<path> — write.
DELETE /v1/<mount>/<path> — delete.
PATCH /v1/<mount>/<path> (KV v2) — partial update.

Each engine documents its own paths via framework.Path.HelpSynopsis. The CLI's vault path-help <mount>/... queries ?help=1 to fetch this.

System (`sys/`) endpoints

vault/logical_system.go (7,766 lines) and vault/logical_system_paths.go (149k lines) define every sys/... endpoint. The major groupings:

Prefix	Concern
`sys/health`	Overall health (always responds, even sealed)
`sys/seal-status`, `sys/seal`, `sys/unseal`	Seal lifecycle
`sys/init`, `sys/init-status`, `sys/rekey/...`, `sys/generate-root/...`	First-time setup, rekey, root token generation
`sys/leader`, `sys/ha-status`, `sys/step-down`	HA
`sys/storage/raft/...`	Integrated Raft (snapshot, autopilot, peers)
`sys/audit`, `sys/audit-hash/...`	Audit device CRUD
`sys/auth`, `sys/mounts`, `sys/remount`	Mount tables
`sys/policy`, `sys/policies/acl`, `sys/policies/rgp`, `sys/policies/egp`	Policy CRUD
`sys/leases/...`	Lease introspection / revocation
`sys/quotas/...`	Rate and lease-count quotas
`sys/plugins/catalog/...`, `sys/plugins/runtimes/catalog/...`, `sys/plugins/reload/...`	Plugin catalog
`sys/wrapping/wrap`, `sys/wrapping/unwrap`, `sys/wrapping/rewrap`, `sys/wrapping/lookup`	Response wrapping
`sys/internal/counters/...`	Activity / client counting
`sys/internal/ui/mounts`, `sys/internal/ui/feature-flags`, `sys/internal/ui/resultant-acl`	UI helper paths
`sys/metrics`, `sys/pprof/...`, `sys/in-flight-req`	Diagnostics
`sys/license/...`	License (Enterprise; CE returns "no license" placeholders)
`sys/replication/...`	Replication (Enterprise; CE returns "disabled")
`sys/namespaces/...`	Namespaces (Enterprise create/patch/delete; CE list-only)
`sys/config/...`	CORS, auditing config, UI custom messages, state, group-policy-application
`sys/mfa/method/...`, `sys/mfa/login-enforcement/...`	Login MFA configuration
`sys/identity/...`	Direct identity-store access (proxied to the `identity/` mount)

`identity/` endpoints

The identity store is mounted at identity/ (not sys/identity), so its paths look like:

identity/entity/...
identity/group/...
identity/oidc/...

Implementation is in vault/identity_store_*.go.

Headers

Header	Direction	Purpose
`X-Vault-Token`	request	Authentication token
`X-Vault-Wrap-TTL`, `X-Vault-Wrap-Format`	request	Response wrapping
`X-Vault-No-Request-Forwarding`	request	Don't forward to active node
`X-Vault-MFA`	request	Login MFA credentials inline
`X-Vault-Policy-Override`	request	Override soft-mandatory Sentinel policies
`X-Vault-Namespace`	request	Namespace selection
`X-Vault-Index`, `X-Vault-Inconsistent`, `X-Vault-Forward`	request	Read-after-write consistency negotiation
`Cache-Control`, `WWW-Authenticate`	response	Standard HTTP semantics applied selectively
`X-Vault-Index`	response	Echoes the cluster's WAL index for the response

Header definitions and parsing live in http/handler.go and vault/cors.go.

Error format

Errors are returned as JSON:

{ "errors": ["1 error occurred:\n\t* permission denied\n\n"] }

HTTP status codes are documented in sdk/logical/response_util.go. The CLI's errwrap.Wrap chains map onto a single errors array.