Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 ยท Concepts and Setup

The Vault HTTP API and CLI

Learn how the Vault HTTP API is organised, how the CLI maps onto it, common headers, status codes, namespaces and output formats, with runnable request-building models.

Vault has one true interface: the HTTP API. The vault command, the web UI and the language SDKs are all clients of it. Understanding the API makes the CLI predictable, helps you debug with curl, and is essential when you call Vault from applications.

This lesson covers the URL layout, authentication header, verbs, status codes, the handy -output-curl-string flag, and a pair of runnable models.

No Vault server is available on this site, so requests cannot be sent. The examples build and interpret requests locally as stand-ins. Response bodies shown are illustrative shapes, not captured output.

URL layout

All API calls start with /v1/, then the mount path, then whatever the plugin defines:

Example Meaning
/v1/sys/health Health and seal state (system backend)
/v1/sys/mounts List or manage secrets engine mounts
/v1/auth/approle/login Log in with AppRole
/v1/secret/data/app/db KV v2 secret
/v1/transit/encrypt/orders Encrypt data with a Transit key
/v1/database/creds/readonly Get dynamic database credentials

Common verbs: GET reads, POST or PUT writes, DELETE deletes, and LIST lists keys (or GET with ?list=true). The CLI verbs map as vault read to GET, vault write to POST/PUT, vault delete to DELETE and vault list to LIST.

Authentication header

After login you send the token in the X-Vault-Token header. Authorization: Bearer <token> is also accepted.

Terminal
curl --header "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/sys/mounts"

Login calls (auth/.../login) are made without a token: they are how you obtain one. The response carries auth.client_token, auth.policies, auth.lease_duration and auth.renewable.

Generic CLI commands

Besides vault kv, the CLI has generic commands that map one-to-one onto paths:

Terminal
vault read    sys/mounts
vault write   transit/encrypt/orders plaintext=$(base64 <<< "card-1234")
vault list    secret/metadata/app
vault delete  secret/metadata/app/db
vault path-help secret/        # describes what a path supports

vault path-help is invaluable with plugins you have not used before. The flag -output-curl-string prints the equivalent curl command instead of sending the request, so you can learn the API from the CLI.

Status codes

Code Typical meaning
200 Success with a body
204 Success, no body
400 Invalid request or missing parameters
403 Permission denied (bad token or policy)
404 Unsupported path or no value found
429 Unsealed and a standby node (in some health checks), or rate limited
500 Internal error
503 Vault is sealed or not ready

Health checks use sys/health, which deliberately uses status codes for node state: 200 active, 429 standby, 472 disaster recovery secondary, 473 performance standby, 501 uninitialized, 503 sealed. Load balancers rely on this.

Building requests

This model builds the curl command and API request for common intents, escaping nothing risky and keeping the token out of the printed text.

Python Build the curl command for a Vault request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

X-Vault-Namespace is an Enterprise feature that scopes the request to a namespace. The open-source edition ignores namespaces.

Interpreting health responses

A load balancer or monitor needs to turn status codes into decisions. This model does exactly that.

Python Decode sys/health status codes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Useful CLI flags and environment variables

Item Purpose
-format=json Machine-readable output; pair with jq
-field=name Print one field only
-output-curl-string Print the equivalent curl command
VAULT_FORMAT Default output format
VAULT_CACERT CA bundle to trust the server's TLS certificate
VAULT_SKIP_VERIFY Skip TLS verification: for testing only, never in production
VAULT_NAMESPACE Default namespace (Enterprise)

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which header carries the Vault token?

    X-Vault-Token (or Authorization with a Bearer token) carries the token.
  2. 2. What does vault list secret/metadata/app map to?

    The CLI list command uses the LIST verb (or GET with list=true).
  3. 3. A health check returns 503. What does it mean?

    sys/health returns 503 for a sealed node and 501 for an uninitialized one.
  4. 4. What does -output-curl-string do?

    It is a quick way to learn the API behind any CLI command.

Summary

  • Everything starts with /v1/ followed by the mount path; the CLI, UI and SDKs all use this API.
  • Send the token in X-Vault-Token; login endpoints return it.
  • vault read/write/list/delete map to GET/POST/LIST/DELETE; path-help and -output-curl-string help you explore.
  • sys/health encodes node state in its status code for load balancers.
  • Never use VAULT_SKIP_VERIFY in production.

Next: The Vault Configuration File