Write new key/value data

[!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.

Write new versions of data to a new or existing data path in the kv v2 plugin.

Assumptions

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

Note

The Vault CLI forcibly converts kv keys and values data to strings before writing data. To preserve non-string data, write your key/value pairs to Vault from a JSON file or use the plugin API.

Use vault kv put to save a new version of key/value data to an new or existing secret path:

$ vault kv put        \
  -mount <mount_path> \
  <secret_path>       \
  <list_of_kv_values>

For example:

$ vault kv put    \
  -mount shared   \
  dev/square-api  \
  sandbox=1234 prod=5679 smoke=abcd

======= Secret Path =======
shared/data/dev/square-api

======= Metadata =======
Key                Value
---                -----
created_time       2024-11-15T01:52:23.434633061Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            5

The Vault GUI forcibly converts non-string keys to strings before writing data. To preserve non-string values, use the JSON toggle to write your key/value data as JSON.

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.

Click Create new + from one of the following tabs:
- Overview tab: in the "Current version" card.
- Secret tab: in the toolbar.
Set a new key name and value.
Use the Add button to set additional key/value pairs.
Click Save to write the new version data.

Partial screenshot of the Vault GUI showing the "Create New Version" screen

Create a JSON file with the key/value data you want to write to Vault. Use the options field to set optional flags and data to define the key/value pairs.

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

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

For example:

{
  "options": {
    "cas": 4
  },
  "data": {
    "sandbox": "1234",
    "prod": "5679",
    "smoke": "abcd"
  }
}

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

{
  "request_id": "0c872d86-0def-4261-34d9-b796039ec02f",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2024-11-15T02:41:02.556301319Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 5
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "kv"
}