Write custom metadata in key/value v2

Write custom metadata to a kv v2 secret path.

Assumptions

You have set up a kv v2 plugin.
Your authentication token has create and update permissions for the kv v2 plugin.

Use vault kv metadata put to set custom metadata fields for a kv mount path. Repeat the -custom-metadata flag for each key/value metadata entry:

$ vault kv metadata put                \
   -custom-metadata <key_value_pair>   \
   -mount <mount_path>                 \
   <secret_path>

For example:

$ vault kv metadata put                                              \
   -custom-metadata "use=API keys for different dev environments"   \
   -custom-metadata "renew-date=2026-11-14"                          \
   -mount shared                                                     \
   dev/square-api

Success! Data written to: shared/metadata/dev/square-api

The custom_metadata metadata field now includes a map with the two custom fields:

$ vault kv metadata get -mount shared dev/square-api

======== Metadata Path ========
shared/metadata/dev/square-api

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2024-11-13T21:51:50.898782695Z
current_version         9
custom_metadata         map[use:API keys for different dev environments renew-date:2026-11-14]
delete_version_after    0s
max_versions            10
oldest_version          4
updated_time            2024-11-15T03:10:26.749233814Z

====== Version 1 ======
Key              Value
---              -----
created_time     2024-11-13T21:51:50.898782695Z
deletion_time    n/a
destroyed        false

Open the data page for your kv plugin:
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.

Click through the path segments to select the relevant secret path.
Select the Metadata tab.
Click Edit metadata >.
Set a new key name and value under Custom metadata.
Use the Add button to set additional key/value pairs.
Click Update.

Partial screenshot of the Vault GUI showing the "Edit Secret Metadata" screen

Create a JSON file with the metadata you want to write to the your kv v2 plugin. Use the custom_metadata field to define the custom metadata fields and initial values.

Make a POST call to /{plugin_mount_path}/metadata/{secret_path} with the JSON data file:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @metadata.json                     \
  ${VAULT_ADDR}/v1/<plugin_mount_path>/metadata/<secret_path>

For example:

{
  "custom_metadata": {
    "use": "API keys for different dev environments",
    "renew-date": "2026-11-14"
  }
}

$ curl                                       \
    --request POST                           \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --data @metadata.json                    \
    ${VAULT_ADDR}/v1/shared/metadata/dev/square-api