---
layout: docs
page_title: Read subkeys
description: >-
   Read the available subkeys on a given path from the kv v2 plugin
---

# Read subkeys for a key/value data path

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

<Tip title="Assumptions">

- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). 
- Your authentication token has `read` permissions for subkeys on the target
  secret path.

</Tip>

<Tabs>

<Tab heading="CLI" group="cli">

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

```shell-session
$ 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:

<CodeBlockConfig hideClipboard="true">

```shell-session
$ 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>]
```

</CodeBlockConfig>

</Tab>

<Tab heading="GUI" group="gui">

@include 'alerts/enterprise-only.mdx'

@include 'gui-instructions/plugins/kv/open-overview.mdx'

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.](/img/gui/kv/overview-page.png)

</Tab>

<Tab heading="API" group="api">

Call the [`/{plugin_mount_path}/subkeys/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#read-secret-subkeys)
endpoint to fetch a list of available subkeys on the given path:

```shell-session
$ 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:

<CodeBlockConfig hideClipboard="true">

```shell-session
$ 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"
}
```

</CodeBlockConfig>

</Tab>

</Tabs>