Mount path
The prefix where an auth method or secrets engine is enabled.
Chapter contract
Prerequisites:
Chapter 2 complete, the shared lab running, and learner.env sourced.
User-visible outcome:
Priya can translate a CLI operation into its exact HTTP mount and KV v2 API route.
Learning objectives
- Read metadata through CLI and API without exposing values.
- Recognize KV v2 data and metadata routes.
- Choose CLI for humans and API or a supported client for applications.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Defines consumption, validation, reload, and stop-using behavior. |
| Platform team owns | Provides trusted runtime identity, protected delivery, network, and telemetry. |
| Vault owns | Operates auth mounts, policies, engines, audit, and recovery. |
Core concepts
API path
The complete route, including engine-specific data or metadata segments.
CLI
A human interface that translates commands into HTTP requests.
UI
A human and operator surface, not an application integration.
Commands and configuration
source learn-vault/.runtime/learner.env
vault secrets list -format=json | jq 'keys'
vault kv metadata get -format=json lockbox-kv/orders-api | jq '{version:.data.current_version}'
curl --silent --show-error --header "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/lockbox-kv/metadata/orders-api" | jq '{version:.data.current_version}'Secret-safety stop
Stop: Do not use curl verbose mode for authenticated requests; it can copy headers and response material into logs.
Failure drill
| Symptom | CLI metadata works but the raw API returns 404. |
|---|---|
| Likely causes | The route omitted /v1, used a friendly KV path, or targeted the wrong mount. |
| Inspect safely | Compare vault secrets list with the API route and request metadata only. |
| Do not print | Expanded curl command, token header, or data response. |
Break it / fix it
Break it: Remove the KV v2 metadata segment from the HTTP route.
Show diagnosis and fix
Fix it: Compare the friendly CLI path with the mounted engine's documented API path.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Compare CLI metadata with its HTTP equivalent, then deliberately omit the KV v2 metadata segment and inspect only the status.
source learn-vault/.runtime/learner.env
vault kv metadata get -format=json lockbox-kv/orders-api | jq -e '.data.current_version>=1'
status=$(curl --silent --output /dev/null --write-out '%{http_code}' --header "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/lockbox-kv/orders-api")
test "$status" = 404 && echo "expected wrong-path response" Success criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- CLI and API metadata report the same current version.
- The deliberately wrong KV v2 route returns 404.
- No command displays stored values.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
Unset VAULT_TOKEN when leaving the shell; retain the shared lab for the next chapter.
Project Lockbox increment
The contract records lockbox-kv as the mount and /v1/lockbox-kv/data/orders-api as the data route.
Quick check
Is the friendly CLI path the literal HTTP route?
No. KV v2 HTTP reads include an engine-specific data segment.
Should an application scrape the UI?
No. Use the HTTP API or a supported client.
Why are mount names contracts?
Consumers embed them in paths, policies, and configuration.
What is safe to compare?
Metadata or selected non-secret fields, not the complete response.
Gotchas
- KV v1 and v2 use different route and response shapes.
- A 404 can conceal a path because of policy.
- Enterprise namespaces add request context beyond the mount.
Recap and next
CLI convenience hides API details; applications need the exact mounted-engine contract.