Skip to main content
Vault Policies define who can access what secrets and with which operations. Policies are written in HashiCorp Configuration Language (HCL) and provide fine-grained access control over Vault paths.

​
Key Concepts

Path-Based Rules

Policies grant capabilities on specific paths. Use wildcards to match multiple paths.

Capabilities

Define allowed operations: create, read, update, delete, list, sudo, deny.

Deny by Default

Users have no access unless explicitly granted by a policy.

Multiple Policies

Users can have multiple policies. Permissions are additive (union of all policies).

​
Required Permissions

ActionPermission
View policiesiam:project:cicd:vault:read
Create/Update policiesiam:project:cicd:vault:write
Delete policiesiam:project:cicd:vault:delete

​
Capabilities Reference

CapabilityDescriptionUse Case
createCreate new data at a pathWriting new secrets
readRead data from a pathViewing secret values
updateModify existing dataChanging secret values
deleteRemove data from a pathDeleting secrets
listList keys at a pathBrowsing folders
sudoAccess root-protected pathsAdmin operations
denyExplicitly deny accessOverride inherited permissions

​
How to Create a Policy

1

Select Vault Instance

Choose the target Vault instance from the dropdown if you have multiple.
2

Click Create Policy

Click the Create Policy button.
3

Enter Policy Name

Provide a unique, descriptive name:
  • Use lowercase with hyphens (e.g., app-read-only)
  • Only alphanumeric, hyphens, and underscores allowed
4

Write Policy Rules

Define access rules in HCL format. Click Insert Example to start with a template.
5

Create

Click Create Policy to save.

​
Policy Syntax

Policies use HCL (HashiCorp Configuration Language) syntax: 
# Grant full access to app secrets
path "secret/data/app/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Read-only access to shared config
path "secret/data/shared/config" {
  capabilities = ["read"]
}

# List folders only (no secret access)
path "secret/metadata/*" {
  capabilities = ["list"]
}

​
Path Patterns

PatternMatches
secret/data/appExact path only
secret/data/app/*All direct children
secret/data/app/+/configSingle-level wildcard
secret/+/*Combination patterns
For KV v2 secrets engine, use secret/data/* for reading/writing secrets and secret/metadata/* for listing and metadata operations.

​
Common Policy Examples

​
Read-Only Policy

# Read and list secrets, no modifications
path "secret/data/*" {
  capabilities = ["read", "list"]
}

path "secret/metadata/*" {
  capabilities = ["list", "read"]
}

​
Application-Specific Policy

# Full access to app's own secrets
path "secret/data/myapp/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

path "secret/metadata/myapp/*" {
  capabilities = ["list", "read", "delete"]
}

# Read shared configuration
path "secret/data/shared/*" {
  capabilities = ["read"]
}

​
Team Lead Policy

# Manage team secrets
path "secret/data/team-alpha/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Read other teams' public configs
path "secret/data/+/public/*" {
  capabilities = ["read"]
}

​
Deny Specific Paths

# Grant broad access
path "secret/data/app/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# But deny access to production credentials
path "secret/data/app/production/credentials" {
  capabilities = ["deny"]
}

​
How to Edit a Policy

1

Find the Policy

Use the search bar to locate the policy by name.
2

Click Edit

Click the edit (pencil) icon on the policy row.
3

Modify Rules

Update the HCL content in the editor.
4

Save

Click Update Policy to apply changes.
Policy changes take effect immediately. Users with active sessions may need to re-authenticate to see updated permissions.

​
How to Delete a Policy

1

Find the Policy

Locate the policy in the list.
2

Click Delete

Click the trash icon on the policy row.
3

Confirm

Confirm the deletion. This action cannot be undone.
Deleting a policy immediately revokes access for all users who depend on it. Ensure no critical workflows rely on this policy before deletion.

​
Best Practices

​
Naming Conventions

{app}-{access-level}          # myapp-read-only
{team}-{resource}-{access}    # platform-secrets-admin
{environment}-{role}          # production-deployer

​
Principle of Least Privilege

Grant minimum necessary permissions: 
# Bad: Too broad
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# Good: Specific and minimal
path "secret/data/myapp/config" {
  capabilities = ["read"]
}

​
Use Comments

Document the purpose of each rule: 
# Allow CI/CD pipeline to read deployment secrets
path "secret/data/deploy/*" {
  capabilities = ["read"]
}

# Allow rotation of API keys only
path "secret/data/api-keys/*" {
  capabilities = ["read", "update"]
}

​
Separate by Environment

Create environment-specific policies: 
# production-app policy
path "secret/data/production/app/*" {
  capabilities = ["read"]
}

# staging-app policy
path "secret/data/staging/app/*" {
  capabilities = ["create", "read", "update", "delete"]
}

​
Troubleshooting

  • Users may need to log out and back in
  • Token may be cached with old permissions
  • Verify the policy is attached to the user/group
  • Check the exact path being accessed matches policy
  • For KV v2, ensure using secret/data/ prefix
  • Verify required capability is included
  • Check for explicit deny rules that may override
  • list capability must be on the metadata path
  • Add: path "secret/metadata/*" { capabilities = ["list"] }
  • Check for missing closing braces }
  • Ensure capabilities are in array format ["read", "list"]
  • Verify no trailing commas in capability arrays
  • Use the Insert Example button to compare syntax
  • You need delete permission for Vault policies
  • Built-in policies (root, default) cannot be deleted
  • Check with administrator for policy management permissions

​
FAQ

Permissions are additive. If policy A grants read and policy B grants write, the user has both read and write access. However, explicit deny always wins.
Use the Vault CLI vault token capabilities command to test what operations are allowed for a token on a specific path.
For KV v2 secrets engine:
  • secret/data/* - Read/write actual secret values
  • secret/metadata/* - List paths, read/write metadata, delete versions
No. Policies are static HCL documents. Use templated policies with Vault Enterprise, or create separate policies per environment.
For full administrative access, attach the root policy. Use sparingly and prefer scoped policies for day-to-day operations.
Yes. MyPolicy and mypolicy are different policies. Use consistent lowercase naming.