Secrets Operations | HashiCorp

Shared fields on every Secrets operation: mount (required — the KV engine mount path, e.g. secret) and engineVersion ("1" or "2", default "2"). Every method below branches on engine version — v1 has no versioning or soft-delete concept, so undelete, destroy, readMetadata, and updateMetadata have no v1 equivalent at all.

read

Reads a secret's data map at an optional specific version (v2) or the current value (v1, which has no versioning).

Field	Type	Required	Description
`path`	text	✓ Yes	Secret path under the mount, e.g. `myapp/db-creds`
`version`	number	No	v2 only — read a specific historical version instead of the current one.

Example response:

{
  "mount": "secret",
  "path": "myapp/db-creds",
  "version": 3,
  "data": { "username": "app_user", "password": "s3cr3t" }
}

write

Writes a flat key/value map to a path. cas enables Check-And-Set on v2 to prevent lost updates.

Field	Type	Required	Description
`path`	text	✓ Yes	Secret path under the mount.
`data`	object	✓ Yes	Flat string/string map — must contain at least one field.
`cas`	number	No	v2 only. `cas: 0` guards against overwriting an existing key — the write fails if any version already exists at the path.

Example response:

{ "mount": "secret", "path": "myapp/db-creds", "version": 4 }

cas semantics: cas: 0 means "only write if the path has never been written" — not "write version 0." Vault rejects the write with a check-and-set error (surfaced here as HASHICORP_CAS_MISMATCH) if the current version doesn't match what you supplied.

delete

Soft delete on v2 (specified versions, or the latest if versions is omitted/empty) — immediately permanent on v1, since v1 has no soft-delete concept at all.

Field	Type	Required	Description
`path`	text	✓ Yes	Secret path under the mount.
`versions`	array of numbers	No	v2 only. Omitted/empty deletes only the latest version.

undelete

v2 only. Restores soft-deleted versions — the counterpart to delete.

Field	Type	Required	Description
`path`	text	✓ Yes	Secret path under the mount.
`versions`	array of numbers	✓ Yes	Which soft-deleted versions to restore.

destroy

v2 only. Permanently destroys the given versions — no undo, unlike delete.

Field	Type	Required	Description
`path`	text	✓ Yes	Secret path under the mount.
`versions`	array of numbers	✓ Yes	Which versions to permanently destroy.

destroy vs. delete: delete is recoverable via undelete on v2. destroy is not recoverable under any circumstances — the version's data is gone from Vault's storage backend.

list

Lists the keys directly under a path.

Field	Type	Required	Description
`path`	text	No	Folder path under the mount. Omit for the mount's root.

Example response:

{
  "mount": "secret",
  "path": "myapp/",
  "count": 2,
  "items": ["db-creds", "api-keys"]
}

Empty folder is not an error: Vault's own API returns HTTP 404 for a genuinely empty LIST path — this node's HTTP client normalizes that into a successful empty-list result rather than an error. A missing folder and an empty folder look identical from Vault, and both are treated as "zero keys," never a failure.

readMetadata

v2 only. Full version history plus retention settings for a path.

Field	Type	Required	Description
`path`	text	✓ Yes	Secret path under the mount.

Example response:

{
  "mount": "secret",
  "path": "myapp/db-creds",
  "currentVersion": 4,
  "oldestVersion": 1,
  "maxVersions": 10,
  "casRequired": false,
  "versions": [
    { "version": 1, "createdTime": "2026-01-05T10:00:00Z", "deletionTime": null, "destroyed": false },
    { "version": 2, "createdTime": "2026-02-11T08:30:00Z", "deletionTime": "2026-02-20T00:00:00Z", "destroyed": false },
    { "version": 3, "createdTime": "2026-03-01T12:00:00Z", "deletionTime": null, "destroyed": true }
  ]
}

updateMetadata

v2 only. Configures retention (max_versions, cas_required) without writing new secret data.

Field	Type	Required	Description
`path`	text	✓ Yes	Secret path under the mount.
`maxVersions`	number	No	Version-count retention limit; older versions age out.
`casRequired`	boolean	No	When true, every future write to this path must supply a `cas` value.

No response caching, by design: this node never caches a Secrets read response — caching a secrets-manager response is a security anti-pattern, not an oversight left for later.