Vault Policies (HCL): Controlling Access by Path and Capability

Vault access control comes down to two questions: which path, and which capability. Miss the design and you either over-grant permissions or end up with calls that simply don't work.

This article walks through path design and capability assignment based on stable Vault behavior, along with wildcard and KV v2 specifics — from both a practical and Associate-exam perspective.

Policy Basics and Evaluation Order

Vault policies are written in HCL, with capabilities defined per path block. On each request, Vault aggregates and evaluates the path blocks that match the requested path across every policy attached to the token. An explicit deny always wins, and if nothing matches the request is denied by default.

The Associate exam frequently tests the meaning of each capability, the precedence of deny, when sudo is required for sys/ operations, and the KV v2 path differences. Always write policies with the actual engine and API path in mind.

• Deny is the default — permissions must be granted explicitly
• When multiple policies match, capabilities are evaluated as a union
• A single deny in any matching policy denies the request
• Privileged sys/ operations may require sudo

Policy evaluation flow (conceptual)

Getting the Path-to-Capability Mapping Right

Capabilities describe the type of operation. In real-world deployments, writes are typically granted as create and update together. The list capability only works on paths where the engine actually exposes a LIST operation.

The mapping to HTTP methods is implementation-dependent in places, but at the Associate level the table below covers what you need for both day-to-day work and the exam.

• read is for reading, list is for listing (when the engine supports it)
• create and update are both writes — some engines split new and existing writes, so grant both to be safe
• delete is required for delete APIs — pay attention to the engine-specific path
• sudo is unnecessary for normal secret operations; it is mostly required under sys/

Wildcards and sys/ Endpoint Caveats

Path blocks support exact matches as well as common wildcards for prefix matching and similar patterns. Over-broad wildcards lead to over-privilege, so keep the prefix as tight as possible.

Paths under sys/ are system administration endpoints: mounts, policy management, health checks, and so on. Many of those operations require an admin token or sudo and should not be granted to application tokens.

• Wildcards are convenient but should be narrowed in scope
• As a rule, do not include sys/ paths in application policies
• Grant capabilities only on the minimum necessary paths

Combining Multiple Policies and the deny-Wins Rule in Practice

When multiple policies are attached to a token, multiple path blocks can match a single request. Capabilities are evaluated as a union, and the presence of even one deny causes the request to be denied. If nothing matches at all, the request is also denied.

There is no automatic 'more specific path wins' precedence between policies — what matters is whether the required capability ends up in the resulting union. For fine-grained control, design with explicit deny statements and adjusted path granularity.

• Multiple grants are evaluated as a union
• deny always takes precedence
• There is no automatic specificity rule — separate concerns explicitly in your design

KV v1 vs v2 Differences and Practical Path Design

The KV secrets engine uses different API paths for v1 and v2. In v2, because of version management, data lives under data/ and listing lives under metadata/. A very common mistake — on the exam and in practice — is granting list on data/ when it actually belongs on metadata/.

Below is a minimal example for an application that needs to read, write, list, and delete under the app/ prefix on a KV v2 engine mounted at secret.

• Reads and writes on v2 go on secret/data/... with read, create, and update
• Listing on v2 goes on secret/metadata/... with list
• Grant delete (soft delete) only where needed, and be cautious with destructive operations

KV v2 HCL policy example (minimal path and capability set)

# app-kv2.hcl
# Mount path: secret (KV v2)

# Read / write / delete: under data
path "secret/data/app/*" {
  capabilities = ["create", "update", "read", "delete"]
}

# List: under metadata (grant list here, not on data)
path "secret/metadata/app/*" {
  capabilities = ["list"]
}

# Operational tips:
# - Do not include sys/ paths in application policies
# - Keep wildcard scopes as narrow as possible

# Apply the policy
# vault policy write app app-kv2.hcl
# Attach the policy and issue a token
# vault token create -policy=app

# Verify (capabilities of the current token on a path)
# vault token capabilities secret/data/app/foo
# vault token capabilities secret/metadata/app/

Validation, Troubleshooting, and Associate Exam Focus Points

Writing the policy is not the end of the job. After attaching it to a token, always verify with vault token capabilities on the target path. The kv CLI subcommand hides the v2 path differences, but policies are still evaluated against the real REST paths — don't forget that.

The exam tests fundamentals like path mistakes (especially v2 metadata/list), the fact that there is no write capability, the precedence of deny, and the sys/-only role of sudo. If you see an option with list on secret/data/, treat it as suspect.

• Verify with vault token capabilities [optional TOKEN] <path>
• When something doesn't work, recheck the path spelling, mount name, and v1/v2 differences
• Avoid granting unnecessary wildcards and sudo

Check Your Understanding

Frequently Asked Questions