Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Your First Secrets with the KV Engine

Write, read, list and delete your first secrets with vault kv commands, understand KV paths and the data/ prefix, and use JSON, fields and curl.

The quickest way to get value from Vault is the KV (key/value) secrets engine. You write a set of key/value pairs at a path and read them back later. The dev server mounts a KV version 2 engine at secret/, so you can start immediately.

This lesson walks through the everyday vault kv commands, explains the extra data/ segment that appears in API paths, and gives you a runnable model of how the CLI turns a command into a request.

Vault is not available on this site, so the commands are read-only. I do not print real output. The Python examples are stand-ins that model path handling and the response shape.

Writing and reading

Assume a dev server and VAULT_ADDR/VAULT_TOKEN set as in Installing Vault and Using Dev Mode.

Terminal
vault kv put -mount=secret app/db username=appuser password='p@ss w0rd'
vault kv get -mount=secret app/db

put stores both keys under the path app/db in the secret mount. get returns the current version, its metadata (version number, creation time) and the data. The older style vault kv put secret/app/db ... also works.

Useful variations:

Terminal
vault kv get -field=password -mount=secret app/db    # just one value, good for scripts
vault kv get -format=json -mount=secret app/db        # machine-readable
vault kv put -mount=secret app/db @data.json          # read data from a file
vault kv list -mount=secret app                       # list keys under a prefix
vault kv delete -mount=secret app/db                  # soft-delete the latest version

Avoid typing real secrets directly on a command line: they land in your shell history. Prefer @file.json, reading from standard input with - as the value, or a secure prompt.

A subtle point: put replaces

Each vault kv put writes a complete new version of the secret. To change a single key and keep the others, use patch:

Terminal
vault kv patch -mount=secret app/db password='n3w-p@ss'

Versioning is the subject of KV Version 2 and Secret Versioning.

Paths, mounts and the data/ prefix

With KV version 2, the CLI hides some details that the HTTP API shows. The same secret is available as:

Layer Path
CLI mount + path -mount=secret app/db
CLI short form secret/app/db
API read GET /v1/secret/data/app/db
API metadata GET /v1/secret/metadata/app/db
Policy path secret/data/app/db

The data/ and metadata/ segments are inserted by the engine. Forgetting that in a policy is one of the most common beginner errors: a policy for secret/app/* does not match secret/data/app/db.

flowchart LR
    CLI["vault kv get secret/app/db"] -->|"CLI inserts data/"| API["GET /v1/secret/data/app/db"]
    API --> E["KV v2 engine at secret/"]

The CLI converts your path into the engine's real API path.

Doing it with curl

Everything the CLI does is an HTTP request. For reference:

Terminal
curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --request POST \
     --data '{"data": {"username": "appuser", "password": "p@ssw0rd"}}' \
     "$VAULT_ADDR/v1/secret/data/app/db"

Note the body wraps your keys in a data object. Reading is a GET to the same URL, and the answer nests your keys under data.data, with metadata under data.metadata.

How the CLI maps a command to a request

This model translates vault kv commands into the API method and path for a KV v2 mount. It is a simplified teaching model.

Python Map vault kv commands to API requests

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.

LIST is a real HTTP method used by Vault; many clients also accept GET with ?list=true.

Unwrapping the response shape

A KV v2 read returns your keys one level deeper than you might expect. This model shows how to pull a field out of such a response.

Python Reading a KV v2 response

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.

Common mistakes

  • Writing a policy for secret/app/* instead of secret/data/app/*.
  • Using vault kv put and expecting it to merge; it creates a new version with only the keys you passed.
  • Putting values with spaces or $ unquoted, so the shell changes them.
  • Storing large files in KV. Keep values small; the default maximum is about 512 KiB.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command changes a single key and keeps the others?

    put writes a complete new version; patch merges the keys you give with the current ones.
  2. 2. What API path serves vault kv get secret/app/db on a KV v2 mount?

    KV v2 inserts data/ between the mount and the secret path.
  3. 3. Why avoid typing secrets directly as command arguments?

    Use @file, standard input or a prompt instead.
  4. 4. Which option prints only one value, useful in scripts?

    -field prints just the named field.

Summary

  • vault kv put, get, list, delete and patch are the everyday commands; put writes a full new version.
  • The dev server provides a KV v2 mount at secret/.
  • The API path inserts data/ (and metadata/), and policies must use those real paths.
  • Keep secrets out of shell history: use files or standard input.
  • Every CLI command is just an HTTP request with the X-Vault-Token header.

Next: Vault Architecture: Barrier, Storage and Paths