Path-Based Routing in Vault: Understanding Mounts and API Structure

Vault expresses everything as HTTP paths. Secret engines and auth methods are "mounted," and requests are routed by longest-prefix match. Getting the path design wrong leads to authorization and compatibility pain, so it pays to nail down the fundamentals.

This article walks through how path resolution works, the differences between KV v1 and v2, the login paths used by auth methods, the sys/ administrative API, and the key points for path-based policies — including the pitfalls that show up frequently on the exam.

The Big Picture: Path Routing and Naming Conventions

Vault's HTTP API is rooted under /v1/, and the leading segment splits into roughly three families: sys/ for administration, auth/ for auth methods, and everything else for user-mounted secret engines. The actual routing is resolved by longest-prefix matching the request path against the mount table.

Even on identical-looking paths, the sub-path layout differs by engine. KV v2 uses data/ and metadata/ sub-paths, while Transit uses encrypt/ and decrypt/. The HTTP verb convention is: GET for reads, POST for writes, LIST for listing (or GET with the list=true query parameter).

• Every API is prefixed with /v1/
• Mounts are resolved by longest-prefix match (for example, with both payments/ and payments/internal/ present, the latter wins)
• Reserved paths: sys/, auth/, and identity/ never collide with user mounts
• Where the LIST method is unavailable, GET with ?list=true works as a substitute
• A trailing slash is generally accepted either way, but it is safer to be consistent

Vault routing resolution (conceptual diagram)

Sanity check: inspect the mount table and routing

export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=<root-or-suitable-token>

# List the mounts
curl -sH "X-Vault-Token: $VAULT_TOKEN" \
  $VAULT_ADDR/v1/sys/mounts | jq .

# Listing when LIST is not permitted (the top level of KV v2, for example)
curl -sH "X-Vault-Token: $VAULT_TOKEN" \
  "$VAULT_ADDR/v1/secret/metadata?list=true" | jq .

Designing Secret Engine Mounts (KV v1/v2 and Transit)

Mount names become part of the API path itself, so settle on vocabulary for environments and domains up front, and pick a hierarchy that anticipates future expansion and migration. KV v2 in particular carries data/ and metadata/ sub-paths and is not wire-compatible with v1.

Transit is an encryption service, with a different API and a different responsibility than a storage-backed KV. Trying to retrofit one into the other quickly creates path and permission mismatches, so use separate mounts and separate policies per purpose.

• KV v2 supports versioning. Read/write goes through secret/data/<name>, metadata through secret/metadata/<name>
• KV v1 is simpler — read/write directly against secret/<name>
• For Transit, you call encrypt/<key> and decrypt/<key> against a key name
• If you anticipate migrations, split mounts along business boundaries, environments, or functions (for example, app/ vs. platform/)
• Include the application name in the first segment to avoid same-name key collisions

KV v2 sub-path layout

secret/ (mount)
  |
  +-- data/<name>      (read and write values: GET/POST)
  +-- metadata/<name>  (metadata and version management)
  +-- destroy/<name>   (permanently remove a specific version)
  +-- delete/<name>    (soft delete: mark a version inactive)

Mount KV v2 at secret/ and read/write a value

# Enable KV v2 (skip if it already exists)
curl -sX POST -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"type":"kv","options":{"version":"2"}}' \
  $VAULT_ADDR/v1/sys/mounts/secret

# Write (KV v2 uses the data/ subpath)
curl -sX POST -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"username":"app","password":"s3cr3t"}}' \
  $VAULT_ADDR/v1/secret/data/app/config | jq .

# Read (the latest version)
curl -sH "X-Vault-Token: $VAULT_TOKEN" \
  $VAULT_ADDR/v1/secret/data/app/config | jq .

# Read a specific version (version=2, for example)
curl -sH "X-Vault-Token: $VAULT_TOKEN" \
  "$VAULT_ADDR/v1/secret/data/app/config?version=2" | jq .

Auth Method Paths and How login Works

Auth methods are mounted under auth/<method>/, and the entry point for token issuance is the login endpoint. Applications call login to obtain a Vault token, then make ordinary API calls against secret engine paths.

You can mount the same method twice under different paths and use them side by side (for example, auth/approle/ and auth/approle-ci/). Since changing the path changes the login endpoint, the mount name has to line up in both the client config and the policy.

• AppRole login is auth/approle/login (send role_id and secret_id)
• Kubernetes login is auth/kubernetes/login (JWT and role)
• Userpass is auth/userpass/login/<username> (the username lives in the path)
• OIDC uses additional paths like callback for the browser flow
• Whenever you change a mount name, update the client config to match

From authentication to reading a secret

App -> POST /v1/auth/<method>/login -> Token
Token -> GET /v1/<mount>/... -> Secret
           ^                      |
           |---- Policy ----------|

Example: AppRole login followed by a read

# Log in with AppRole
curl -sX POST -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role_id":"<ROLE_ID>","secret_id":"<SECRET_ID>"}' \
  $VAULT_ADDR/v1/auth/approle/login | jq .

# Read KV v2 with the client_token you received
APP_TOKEN=<client_token_from_response>
curl -sH "X-Vault-Token: $APP_TOKEN" \
  $VAULT_ADDR/v1/secret/data/app/config | jq .

System APIs and Metadata: When to Use sys/

sys/ is Vault's administrative API surface, handling enabling and configuring mounts and auth methods, health checks, policies, and token inspection. Application code rarely calls it directly; it shows up heavily in operations and automation (Terraform, CI).

These permissions are powerful, so restrict them to the minimum paths necessary. As a rule, grant sys/mounts/* and sys/auth/* only to administrative roles, never to applications.

• sys/mounts: secret engine management (enable, tune, disable)
• sys/auth: auth method management
• sys/health: health check (read-only)
• sys/capabilities[-self]: inspect a token's permissions
• Lease-related operations live under sys/leases for lookup and revocation

How sys/ APIs are organized

Typical sys/ operations

# Enable the Transit engine
curl -sX POST -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"transit"}' \
  $VAULT_ADDR/v1/sys/mounts/transit

# Set max_versions on KV v2 to 10
data='{"options":{"version":"2"},"description":"App secrets","max_versions":10}'
curl -sX POST -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$data" \
  $VAULT_ADDR/v1/sys/mounts/secret/tune

# Check your own token's rights
curl -sX POST -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths":["secret/data/app/*","sys/mounts"]}' \
  $VAULT_ADDR/v1/sys/capabilities-self | jq .

Path-Based Policies and Practical Permission Design

Vault ACL policies grant capabilities per path. Because KV v2 treats data/ and metadata/ separately, granting read-only access usually means at least reading data/ and considering list on metadata/. Also distinguish destroy from delete.

Because routing uses longest-prefix match, mixing broad allows with narrow denies makes things complicated fast. As a rule, allow only what is necessary, and avoid wildcards you do not actually need.

• KV v2 read: grant read on path "secret/data/app/*"
• If you need to list keys, grant list on path "secret/metadata/app"
• Writes need create and update on data/
• Permanent version deletion needs delete on destroy/ (grant carefully)
• As a rule, do not grant sys/ permissions to applications

How a request is evaluated against policy

Request: GET /v1/secret/data/app/config
   |
   v
[the set of policies]
  - path "secret/data/app/*" { capabilities = ["read"] }
  - path "secret/metadata/*" { capabilities = ["list"] }
   |
   v
 Verdict: allowed (read matches)

Example least-privilege policy and how to verify it

# Policy definition (HCL)
cat > app-readonly.hcl <<'EOF'
path "secret/data/app/*" {
  capabilities = ["read"]
}
path "secret/metadata/app" {
  capabilities = ["list"]
}
EOF

# Create the policy
curl -sX PUT -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- $VAULT_ADDR/v1/sys/policies/acl/app-readonly <<'JSON'
{"policy": "$(sed 's/"/\\"/g' app-readonly.hcl)"}
JSON

# Self-diagnose your token's capabilities
curl -sX POST -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths":["secret/data/app/config","secret/metadata/app"]}' \
  $VAULT_ADDR/v1/sys/capabilities-self | jq .

Check Yourself with a Question

Frequently Asked Questions