Skip to main content
When defining Vault policies, you specify both the path you’re granting privileges to and the capabilities allowed on that path. Capabilities control what actions can be performed—such as creating or reading secrets, listing entries, or even explicitly denying access. They map closely to HTTP verbs and are always defined as a list of strings under the capabilities field.

​
Capability Matrix

CapabilityHTTP MethodDescription
createPOST or PUT (new key)Write a brand-new secret
readGETRetrieve a secret or configuration
updatePOST or PUT (existing key)Overwrite or change an existing secret
deleteDELETERemove a secret or configuration
listLISTEnumerate keys under a path (no values)
sudoN/APerform operations on root-protected paths
denyN/AExplicitly block access (overrides others)
Vault does not support a write capability. Instead, policies use separate create and update actions.
The image lists various "Vault Policies - Capabilities" such as Create, Read, Update, Delete, List, Sudo, and Deny, with a note stating that "Write" is not a valid capability.

​
Create vs. Update

  • create: Required for writing a brand-new key (it must not exist yet).
  • update: Required to modify an existing key’s value.
If you grant only create, users cannot modify existing keys. If you grant only update, users cannot create new keys.

​
Other Capabilities

  • read: Retrieve secrets or configurations.
  • delete: Remove secrets or configurations.
  • list: View which keys exist under a path (without reading their values).
  • sudo: Perform operations on root-protected paths.
  • deny: Block access regardless of any other capability rules.

​
Example Policy: Database Credentials & App Secrets

Suppose you need:
  1. read access to database credentials at database/creds/dev-db01.
  2. create, read, update, and delete permissions for secrets under kv/apps/dev-app01.
You can combine these into a single policy with two path blocks: 
path "database/creds/dev-db01" {
  capabilities = ["read"]
}

path "kv/apps/dev-app01" {
  capabilities = ["create", "read", "update", "delete"]
}
Once applied, your application can generate dynamic credentials for dev-db01 and fully manage secrets under kv/apps/dev-app01.

​
Example Policy with Wildcards & Deny

Imagine a KV secrets engine mounted at kv/ with this directory structure: 
kv/
└─ apps/
   ├─ webapp/
   │  ├─ super_secret
   │  ├─ API_token
   │  └─ hostname
   ├─ mid-tier/
   └─ database/
Requirements:
  • Grant read access to everything under kv/apps/webapp/.
  • Deny access to kv/apps/webapp/super_secret.
The image shows an example of a Vault policy with requirements for accessing and denying access to specific paths in a key-value store. It includes a directory tree structure illustrating the paths.
Use a wildcard for the first rule and an explicit deny for the second: 
path "kv/apps/webapp/*" {
  capabilities = ["read"]
}

path "kv/apps/webapp/super_secret" {
  capabilities = ["deny"]
}
  • Users can read any current or future secrets under webapp/ (e.g., API_token, hostname).
  • The explicit deny ensures super_secret remains inaccessible.

​
Pop Quiz #1

Does the above policy permit reading the path kv/apps/webapp itself?
Answer: No. The pattern kv/apps/webapp/* matches entries beneath webapp/, not the directory itself.

​
Pop Quiz #2

Can a user with only the above policy browse to kv/apps/webapp in the UI or list its contents via CLI?
Answer: No. Browsing or listing requires the list capability on each parent path. To enable navigation, extend the policy: 
path "kv" {
  capabilities = ["list"]
}

path "kv/apps" {
  capabilities = ["list"]
}

path "kv/apps/webapp" {
  capabilities = ["list"]
}

path "kv/apps/webapp/*" {
  capabilities = ["read", "list"]
}

path "kv/apps/webapp/super_secret" {
  capabilities = ["deny"]
}
Without list on each parent path, users cannot navigate the directory structure in the Vault UI or via the CLI.

​
References

Watch Video