diff --git a/changelog/13893.txt b/changelog/13893.txt new file mode 100644 index 000000000..d7ff9439d --- /dev/null +++ b/changelog/13893.txt @@ -0,0 +1,3 @@ +```release-note:improvement +secrets/kv: add subkeys endpoint to retrieve a secret's stucture without its values +``` diff --git a/website/content/api-docs/secret/kv/kv-v2.mdx b/website/content/api-docs/secret/kv/kv-v2.mdx index bd2949e36..cf986ac77 100644 --- a/website/content/api-docs/secret/kv/kv-v2.mdx +++ b/website/content/api-docs/secret/kv/kv-v2.mdx @@ -274,6 +274,69 @@ $ curl \ } ``` +## Read Secret Subkeys + +This endpoint provides the subkeys within a secret entry that exists +at the requested path. The secret entry at this path will be retrieved +and stripped of all data by replacing underlying values of leaf keys +(i.e. non-map keys or map keys with no underlying subkeys) with `null`. + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/secret/subkeys/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. +- `version` `(int: 0)` - Specifies the version to return. If not set the latest + version is returned. +- `depth` `(int: 0)` - Specifies the deepest nesting level to provide in the output. + The default value 0 will not impose any limit. If non-zero, keys that reside at the + specified `depth` value will be artificially treated as leaves and will thus be `null` + even if further underlying subkeys exist. + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/secret/subkeys/my-secret?version=1 +``` + +### Sample Secret Data + +```json +{ + "foo": "abc", + "bar": { + "baz": "def" + }, + "quux": {} +} +``` + +### Sample Response + +```json +{ + "subkeys": { + "foo": null, + "bar": { + "baz": null + }, + "quux": null + }, + "metadata": { + "created_time": "2021-12-14T20:28:00.773477Z", + "custom_metadata": null, + "deletion_time": "", + "destroyed": false, + "version": 1 + } +} +``` + ## Delete Latest Version of Secret This endpoint issues a soft delete of the secret's latest version at the @@ -562,6 +625,7 @@ $ curl \ ``` ## Patch Metadata + This endpoint patches an existing metadata entry of a secret at the specified location. The calling token must have an ACL policy granting the `patch` capability. Currently, only JSON merge patch is supported and must be specified @@ -599,7 +663,7 @@ not create a new version. { "max_versions": 5, "custom_metadata": { - "bar": "123", + "bar": "123" } } ```