706 lines
18 KiB
Plaintext
706 lines
18 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: KV - Secrets Engines - HTTP API
|
||
description: This is the API documentation for the Vault KV secrets engine.
|
||
---
|
||
|
||
# KV Secrets Engine - Version 2 (API)
|
||
|
||
This is the API documentation for the Vault KV secrets engine while running in
|
||
versioned mode. For general information about the usage and operation of the kv
|
||
secrets engine, please see the [Vault kv
|
||
documentation](/docs/secrets/kv).
|
||
|
||
This documentation assumes the kv secrets engine is enabled at the
|
||
`/secret` path in Vault and that versioning has been enabled. Since it is
|
||
possible to enable secrets engines at any location, please update your API calls
|
||
accordingly.
|
||
|
||
## Configure the KV Engine
|
||
|
||
This path configures backend level settings that are applied to every key in the
|
||
key-value store.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------- |
|
||
| `POST` | `/secret/config` |
|
||
|
||
### Parameters
|
||
|
||
- `max_versions` `(int: 0)` – The number of versions to keep per key. This value
|
||
applies to all keys, but a key's metadata setting can overwrite this value.
|
||
Once a key has more than the configured allowed versions, the oldest version
|
||
will be permanently deleted. When 0 is used or the value is unset, Vault
|
||
will keep 10 versions.
|
||
|
||
- `cas_required` `(bool: false)` – If true all keys will require the cas
|
||
parameter to be set on all write requests.
|
||
|
||
- `delete_version_after` `(string:"0s")` – If set, specifies the length
|
||
of time before a version is deleted.
|
||
Accepts [duration format strings](/docs/concepts/duration-format).
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"max_versions": 5,
|
||
"cas_required": false,
|
||
"delete_version_after": "3h25m19s"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/config
|
||
```
|
||
|
||
## Read KV Engine configuration
|
||
|
||
This path retrieves the current configuration for the secrets backend at the
|
||
given path.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------- |
|
||
| `GET` | `/secret/config` |
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://127.0.0.1:8200/v1/secret/config
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"cas_required": false,
|
||
"delete_version_after": "3h25m19s",
|
||
"max_versions": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
## Read Secret Version
|
||
|
||
This endpoint retrieves the secret at the specified location. The metadata
|
||
fields `created_time`, `deletion_time`, `destroyed`, and `version` are version
|
||
specific. The `custom_metadata` field is part of the secret's key metadata and
|
||
is included in the response whether or not the calling token has `read` access to
|
||
the associated [metadata endpoint](/api-docs/secret/kv/kv-v2#read-secret-metadata).
|
||
|
||
| Method | Path |
|
||
| :----- | :------------------------------------------- |
|
||
| `GET` | `/secret/data/:path?version=:version-number` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to read.
|
||
This is specified as part of the URL.
|
||
- `version` `(int: 0)` - Specifies the version to return. If not set the latest
|
||
version is returned.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://127.0.0.1:8200/v1/secret/data/my-secret?version=2
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"data": {
|
||
"foo": "bar"
|
||
},
|
||
"metadata": {
|
||
"created_time": "2018-03-22T02:24:06.945319214Z",
|
||
"custom_metadata": {
|
||
"owner": "jdoe",
|
||
"mission_critical": "false"
|
||
},
|
||
"deletion_time": "",
|
||
"destroyed": false,
|
||
"version": 2
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Create/Update Secret
|
||
|
||
This endpoint creates a new version of a secret at the specified location. If
|
||
the value does not yet exist, the calling token must have an ACL policy granting
|
||
the `create` capability. If the value already exists, the calling token must
|
||
have an ACL policy granting the `update` capability.
|
||
|
||
| Method | Path |
|
||
| :----- | :------------------- |
|
||
| `POST` | `/secret/data/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `options` `(Map: <optional>)` – An object that holds option settings.
|
||
|
||
- `cas` `(int: <optional>)` - This flag is required if cas_required is set
|
||
to true on either the secret or the engine's config. If not set the write
|
||
will be allowed. In order for a write to be successful, `cas` must be set to
|
||
the current version of the secret. If set to 0 a write will only be allowed if
|
||
the key doesn’t exist as unset keys do not have any version information. Also
|
||
remember that soft deletes do not remove any underlying version data from storage.
|
||
In order to write to a soft deleted key, the cas parameter must match the key's
|
||
current version.
|
||
|
||
- `data` `(Map: <required>)` – The contents of the data map will be stored and
|
||
returned on read.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"options": {
|
||
"cas": 0
|
||
},
|
||
"data": {
|
||
"foo": "bar",
|
||
"zip": "zap"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/data/my-secret
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"created_time": "2018-03-22T02:36:43.986212308Z",
|
||
"custom_metadata": {
|
||
"owner": "jdoe",
|
||
"mission_critical": "false"
|
||
},
|
||
"deletion_time": "",
|
||
"destroyed": false,
|
||
"version": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
## Patch Secret
|
||
|
||
This endpoint provides the ability to patch an _existing_ secret at the specified
|
||
location. The secret must neither be deleted nor destroyed. The calling token must
|
||
have an ACL policy granting the `patch` capability. Currently, only
|
||
[JSON merge patch](https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-json-merge-patch-07)
|
||
is supported and must be specified using a `Content-Type` header value of
|
||
`application/merge-patch+json`. A new version will be created upon successfully
|
||
applying a patch with the provided data.
|
||
|
||
| Method | Path |
|
||
| :------ | :------------------- |
|
||
| `PATCH` | `/secret/data/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `options` `(Map: <optional>)` – An object that holds option settings.
|
||
|
||
- `cas` `(int: <optional>)` - This flag is required if `cas_required` is set to true on either
|
||
the secret or the engine's config. In order for a write to be successful, `cas` must be set
|
||
to the current version of the secret. A patch operation must be attempted on an existing
|
||
key, thus the provided `cas` value must be greater than 0.
|
||
|
||
- `data` `(Map: <required>)` – The contents of the data map will be applied as a partial
|
||
update to the existing entry via a JSON merge patch to the existing entry.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"options": {
|
||
"cas": 1
|
||
},
|
||
"data": {
|
||
"foo": "a",
|
||
"bar": {
|
||
"baz": "b"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--header "Content-Type: application/merge-patch+json"
|
||
--request PATCH \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/data/my-secret
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"created_time": "2021-09-10T15:26:08.684999Z",
|
||
"custom_metadata": {
|
||
"owner": "jdoe",
|
||
"mission_critical": "false"
|
||
},
|
||
"deletion_time": "",
|
||
"destroyed": false,
|
||
"version": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
## Read Secret Subkeys
|
||
|
||
This endpoint provides the subkeys within a secret entry that exists
|
||
at the requested path. The secret entry at this path will be retrieved
|
||
and stripped of all data by replacing underlying values of leaf keys
|
||
(i.e. non-map keys or map keys with no underlying subkeys) with `null`.
|
||
|
||
| Method | Path |
|
||
| :----- | :---------------------- |
|
||
| `GET` | `/secret/subkeys/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to read.
|
||
This is specified as part of the URL.
|
||
- `version` `(int: 0)` - Specifies the version to return. If not set the latest
|
||
version is returned.
|
||
- `depth` `(int: 0)` - Specifies the deepest nesting level to provide in the output.
|
||
The default value 0 will not impose any limit. If non-zero, keys that reside at the
|
||
specified `depth` value will be artificially treated as leaves and will thus be `null`
|
||
even if further underlying subkeys exist.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://127.0.0.1:8200/v1/secret/subkeys/my-secret?version=1
|
||
```
|
||
|
||
### Sample Secret Data
|
||
|
||
```json
|
||
{
|
||
"foo": "abc",
|
||
"bar": {
|
||
"baz": "def"
|
||
},
|
||
"quux": {}
|
||
}
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"subkeys": {
|
||
"foo": null,
|
||
"bar": {
|
||
"baz": null
|
||
},
|
||
"quux": null
|
||
},
|
||
"metadata": {
|
||
"created_time": "2021-12-14T20:28:00.773477Z",
|
||
"custom_metadata": null,
|
||
"deletion_time": "",
|
||
"destroyed": false,
|
||
"version": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Latest Version of Secret
|
||
|
||
This endpoint issues a soft delete of the secret's latest version at the
|
||
specified location. This marks the version as deleted and will stop it from
|
||
being returned from reads, but the underlying data will not be removed. A
|
||
delete can be undone using the `undelete` path.
|
||
|
||
| Method | Path |
|
||
| :------- | :------------------- |
|
||
| `DELETE` | `/secret/data/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
|
||
This is specified as part of the URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
https://127.0.0.1:8200/v1/secret/data/my-secret
|
||
```
|
||
|
||
## Delete Secret Versions
|
||
|
||
This endpoint issues a soft delete of the specified versions of the secret. This
|
||
marks the versions as deleted and will stop them from being returned from reads,
|
||
but the underlying data will not be removed. A delete can be undone using the
|
||
`undelete` path.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------- |
|
||
| `POST` | `/secret/delete/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
|
||
This is specified as part of the URL.
|
||
- `versions` `([]int: <required>)` - The versions to be deleted. The versioned
|
||
data will not be deleted, but it will no longer be returned in normal get
|
||
requests.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"versions": [1, 2]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/delete/my-secret
|
||
```
|
||
|
||
## Undelete Secret Versions
|
||
|
||
Undeletes the data for the provided version and path in the key-value store.
|
||
This restores the data, allowing it to be returned on get requests.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------- |
|
||
| `POST` | `/secret/undelete/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to undelete.
|
||
This is specified as part of the URL.
|
||
|
||
- `versions` `([]int: <required>)` - The versions to undelete. The versions will
|
||
be restored and their data will be returned on normal get requests.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"versions": [1, 2]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/undelete/my-secret
|
||
```
|
||
|
||
## Destroy Secret Versions
|
||
|
||
Permanently removes the specified version data for the provided key and version
|
||
numbers from the key-value store.
|
||
|
||
| Method | Path |
|
||
| :----- | :---------------------- |
|
||
| `POST` | `/secret/destroy/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to destroy.
|
||
This is specified as part of the URL.
|
||
|
||
- `versions` `([]int: <required>)` - The versions to destroy. Their data will be
|
||
permanently deleted.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"versions": [1, 2]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/destroy/my-secret
|
||
```
|
||
|
||
## List Secrets
|
||
|
||
This endpoint returns a list of key names at the specified location. Folders are
|
||
suffixed with `/`. The input must be a folder; list on a file will not return a
|
||
value. Note that no policy-based filtering is performed on keys; do not encode
|
||
sensitive information in key names. The values themselves are not accessible via
|
||
this command.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------- |
|
||
| `LIST` | `/secret/metadata/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secrets to list.
|
||
This is specified as part of the URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
https://127.0.0.1:8200/v1/secret/metadata/my-secret
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
The example below shows output for a query path of `secret/` when there are
|
||
secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two
|
||
entries.
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": ["foo", "foo/"]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Read Secret Metadata
|
||
|
||
This endpoint retrieves the metadata and versions for the secret at the
|
||
specified path. Metadata is version-agnostic.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------- |
|
||
| `GET` | `/secret/metadata/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to read.
|
||
This is specified as part of the URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://127.0.0.1:8200/v1/secret/metadata/my-secret
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"cas_required": false,
|
||
"created_time": "2018-03-22T02:24:06.945319214Z",
|
||
"current_version": 3,
|
||
"delete_version_after": "3h25m19s",
|
||
"max_versions": 0,
|
||
"oldest_version": 0,
|
||
"updated_time": "2018-03-22T02:36:43.986212308Z",
|
||
"custom_metadata": {
|
||
"foo": "abc",
|
||
"bar": "123",
|
||
"baz": "5c07d823-3810-48f6-a147-4c06b5219e84"
|
||
},
|
||
"versions": {
|
||
"1": {
|
||
"created_time": "2018-03-22T02:24:06.945319214Z",
|
||
"deletion_time": "",
|
||
"destroyed": false
|
||
},
|
||
"2": {
|
||
"created_time": "2018-03-22T02:36:33.954880664Z",
|
||
"deletion_time": "",
|
||
"destroyed": false
|
||
},
|
||
"3": {
|
||
"created_time": "2018-03-22T02:36:43.986212308Z",
|
||
"deletion_time": "",
|
||
"destroyed": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Create/Update Metadata
|
||
|
||
This endpoint creates or updates the metadata of a secret at the specified location.
|
||
It does not create a new version.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------- |
|
||
| `POST` | `/secret/metadata/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `max_versions` `(int: 0)` – The number of versions to keep per key. If not
|
||
set, the backend’s configured max version is used. Once a key has more than
|
||
the configured allowed versions, the oldest version will be permanently
|
||
deleted.
|
||
|
||
- `cas_required` `(bool: false)` – If true, the key will require the `cas`
|
||
parameter to be set on all write requests. If false, the backend’s
|
||
configuration will be used.
|
||
|
||
- `delete_version_after` `(string:"0s")` – Set the `delete_version_after` value
|
||
to a duration to specify the `deletion_time` for all new versions
|
||
written to this key. If not set, the backend's `delete_version_after` will be
|
||
used. If the value is greater than the backend's `delete_version_after`, the
|
||
backend's `delete_version_after` will be used. Accepts [Go duration
|
||
format string][duration-godoc].
|
||
|
||
- `custom_metadata` `(map<string|string>: nil)` - A map of arbitrary string to string valued user-provided metadata meant
|
||
to describe the secret.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"max_versions": 5,
|
||
"cas_required": false,
|
||
"delete_version_after": "3h25m19s",
|
||
"custom_metadata": {
|
||
"foo": "abc",
|
||
"bar": "123",
|
||
"baz": "5c07d823-3810-48f6-a147-4c06b5219e84"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/metadata/my-secret
|
||
```
|
||
|
||
## Patch Metadata
|
||
|
||
This endpoint patches an existing metadata entry of a secret at the specified
|
||
location. The calling token must have an ACL policy granting the `patch`
|
||
capability. Currently, only JSON merge patch is supported and must be specified
|
||
using a `Content-Type` header value of `application/merge-patch+json`. It does
|
||
not create a new version.
|
||
|
||
| Method | Path |
|
||
| :------ | :----------------------- |
|
||
| `PATCH` | `/secret/metadata/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `max_versions` `(int: 0)` – The number of versions to keep per key. If not
|
||
set, the backend’s configured max version is used. Once a key has more than
|
||
the configured allowed versions, the oldest version will be permanently
|
||
deleted.
|
||
|
||
- `cas_required` `(bool: false)` – If true, the key will require the `cas`
|
||
parameter to be set on all write requests. If false, the backend’s
|
||
configuration will be used.
|
||
|
||
- `delete_version_after` `(string:"0s")` – Set the `delete_version_after` value
|
||
to a duration to specify the `deletion_time` for all new versions
|
||
written to this key. If not set, the backend's `delete_version_after` will be
|
||
used. If the value is greater than the backend's `delete_version_after`, the
|
||
backend's `delete_version_after` will be used. Accepts [duration format
|
||
strings](/docs/concepts/duration-format).
|
||
|
||
- `custom_metadata` `(map<string|string>: nil)` - A map of arbitrary string to string valued user-provided metadata meant
|
||
to describe the secret.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"max_versions": 5,
|
||
"custom_metadata": {
|
||
"bar": "123"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--header "Content-Type: application/merge-patch+json"
|
||
--request PATCH \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/secret/metadata/my-secret
|
||
```
|
||
|
||
## Delete Metadata and All Versions
|
||
|
||
This endpoint permanently deletes the key metadata and all version data for the
|
||
specified key. All version history will be removed.
|
||
|
||
| Method | Path |
|
||
| :------- | :----------------------- |
|
||
| `DELETE` | `/secret/metadata/:path` |
|
||
|
||
### Parameters
|
||
|
||
- `path` `(string: <required>)` – Specifies the path of the secret to delete.
|
||
This is specified as part of the URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
https://127.0.0.1:8200/v1/secret/metadata/my-secret
|
||
```
|