Read subkeys for a key/value data path

[!IMPORTANT]
Documentation Update: Product documentation, which were located in this repository under /website, are now located in hashicorp/web-unified-docs, colocated with all other product documentation. Contributions to this content should be done in the web-unified-docs repo, and not this one. Changes made to /website content in this repo will not be reflected on the developer.hashicorp.com website.

Read the available subkeys on an existing data path in the kv v2 plugin.

Assumptions

You have set up a kv v2 plugin.
Your authentication token has read permissions for subkeys on the target secret path.

Use vault read with the /subkeys path to retrieve a list of secret data subkeys at the given path.

$ vault read <mount_path>/subkeys/<secret_path>

Vault retrieves secrets at the given path but replaces the underlying values of non-map keys and map keys with no underlying subkeys (leaf keys) with nil.

For example:

$ vault read shared/subkeys/dev/square-api

Key         Value
---         -----
metadata    map[created_time:2024-11-20T20:00:13.385182722Z custom_metadata:<nil> deletion_time: destroyed:false version:1]
subkeys     map[prod:<nil> sandbox:<nil> smoke:<nil>]

Appropriate Vault Enterprise license required

Open the Overview screen for your secret path:
1. Open the GUI for your Vault instance.
2. Login under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu and re-authenticate.
3. Select Secrets Engines from the left-hand menu.
4. Select the mount path for your kv plugin.
5. Click through the path segments to select the relevant secret path.

You can read a list of available subkeys for the target path in the Subkeys card.

Partial screenshot of the Vault GUI showing subkeys "prod" and "sandbox" for secret data at path dev/square-api.

Call the /{plugin_mount_path}/subkeys/{secret_path} endpoint to fetch a list of available subkeys on the given path:

$ curl                                       \
   --request GET                             \
   --header "X-Vault-Token: ${VAULT_TOKEN}"  \
   ${VAULT_ADDR}/v1/<plugin_mount_path>/subkeys/<secret_path>

Vault retrieves secrets at the given path but replaces the underlying values of non-map keys and map keys with no underlying subkeys (leaf keys) with null.

For example:

$ curl                                       \
   --request GET                             \
   --header "X-Vault-Token: ${VAULT_TOKEN}"  \
   ${VAULT_ADDR}/v1/shared/subkeys/dev/square-api | jq

{
  "request_id": "bfeac3c5-f4dc-37b2-8909-3b15121cfd20",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "metadata": {
      "created_time": "2024-11-20T20:00:13.385182722Z",
      "custom_metadata": null,
      "deletion_time": "",
      "destroyed": false,
      "version": 11
    },
    "subkeys": {
      "prod": null,
      "sandbox": null,
      "smoke": null
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "kv"
}