---
layout: docs
page_title: Write custom metadata
description: >-
   Write custom metadata fields to your kv v2 plugin.
---

# Write custom metadata in key/value v2 

Write custom metadata to a `kv` v2 secret path.

<Tip title="Assumptions">

- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup). 
- Your authentication token has `create` and `update` permissions for the `kv`
  v2 plugin.

</Tip>

<Tabs>

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

Use [`vault kv metadata put`](/vault/docs/command/kv/metadata) to set custom
metadata fields for a `kv` mount path. Repeat the `-custom-metadata` flag for
each key/value metadata entry:

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

For example: 

<CodeBlockConfig hideClipboard="true">

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


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

<CodeBlockConfig hideClipboard="true" highlight="14">

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

</CodeBlockConfig>

</Tab>

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

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

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

</Tab>

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

1. 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.

1. Make a `POST` call to
   [`/{plugin_mount_path}/metadata/{secret_path}`](/vault/api-docs/secret/kv/kv-v2#create-update-metadata)
   with the JSON data file:
    ```shell-session
    $ curl                                      \
      --request POST                            \
      --header "X-Vault-Token: ${VAULT_TOKEN}"  \
      --data @metadata.json                     \
      ${VAULT_ADDR}/v1/<plugin_mount_path>/metadata/<secret_path>
    ```

For example:

<CodeBlockConfig hideClipboard="true">

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

</CodeBlockConfig>

<CodeBlockConfig hideClipboard="true">

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

`/{plugin_mount_path}/metadata/{secret_path}` does not return data on success.

</CodeBlockConfig>

</Tab>

</Tabs>