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-apiSuccess! 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            falsecreated_time            2024-11-13T21:51:50.898782695Zcurrent_version         9custom_metadata         map[use:API keys for different dev environments renew-date:2026-11-14]delete_version_after    0smax_versions            10oldest_version          4updated_time            2024-11-15T03:10:26.749233814Z====== Version 1 ======Key              Value---              -----created_time     2024-11-13T21:51:50.898782695Zdeletion_time    n/adestroyed        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