Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

Движки секретов. KV - версия 2 (API)

Это документация API для движка секретов StarVault KV, работающего в версионном режиме. Общую информацию об использовании и работе движка секретов KV версии 2 см. в документации StarVault KV.

1. Настройка движка KV

Этот путь настраивает параметры на уровне движка, применяемые к каждому ключу в хранилище «ключ-значение».

Метод Путь

POST

/:secret-mount-path/config

1.1. Параметры

  • secret-mount-path (string: <required>) - путь к монтированию KV в конфигурации, например, secret. Указывается как часть URL.

  • max_versions (int: 0) - количество хранимых версий для каждого ключа. Это значение применяется ко всем ключам, но настройки метаданных ключа могут перезаписать это значение. Как только у ключа будет больше версий, чем задано в настройках, самая старая версия будет удалена без возможности восстановления. Если используется 0 или значение не задано, StarVault сохранит 10 версий.

  • cas_required (bool: false) - если true, для всех ключей потребуется установка параметра cas для всех запросов на запись.

  • delete_version_after (string:"0s") - если установлено, указывает время до удаления версии.

Пример тела запроса:
{
  "max_versions": 5,
  "cas_required": false,
  "delete_version_after": "3h25m19s"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/secret/config

2. Чтение конфигурации движка KV

Эта конечная точка извлекает текущую конфигурацию движка секретов по указанному пути.

Метод Путь

GET

/:secret-mount-path/config

2.1. Параметры

  • secret-mount-path (строка: <обязательно>) - путь к точке монтирования KV для чтения конфигурации, например, secret. Указывается как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/secret/config
Пример ответа:
{
  "data": {
    "cas_required": false,
    "delete_version_after": "3h25m19s",
    "max_versions": 0
  }
}

3. Чтение версии секрета

Эта конечная точка извлекает секрет из указанного места. Поля метаданных created_time, deletion_time, destroyed и version зависят от версии. Поле custom_metadata является частью метаданных ключа секрета и включается в ответ независимо от того, имеет ли вызывающий токен право read на связанную [конечную точку метаданных] (/api-docs/secret/kv/kv-v2#read-secret-metadata).

Метод Путь

GET

/:secret-mount-path/data/:path?version=:version-number

3.1. Параметры

  • secret-mount-path (string: <required>) - путь к точке монтирования KV, содержащей секрет для чтения, например, secret. Указывается как часть URL.

  • path (string: <required>) - указывает путь к секрету для чтения. Указывается как часть URL.

  • version (int: 0) - указывает возвращаемую версию. Если не указано, возвращается последняя версия.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/secret/data/my-secret?version=2
Пример ответа:
{
  "data": {
    "data": {
      "foo": "bar"
    },
    "metadata": {
      "created_time": "2025-07-30T11:24:18.377172189Z",
      "custom_metadata": {
        "owner": "jdoe",
        "mission_critical": "false"
      },
      "deletion_time": "",
      "destroyed": false,
      "version": 2
    }
  }
}

4. Создать/обновить секрет

Эта конечная точка Создаёт новую версию секрета в указанном месте. Если значение ещё не существует, вызывающий токен должен иметь политику ACL, предоставляющую возможность create. Если значение уже существует, вызывающий токен должен иметь политику ACL, предоставляющую возможность update.

Метод Путь

POST

/:secret-mount-path/data/:path

5. Параметры

  • secret-mount-path (строка: <required>) - путь к точке монтирования KV, содержащей секрет для обновления, например, secret. Указывается как часть URL-адреса.

  • path (строка: <required>) - указывает путь к секрету для обновления. Указывается как часть URL-адреса.

  • options (Map: <optional>) - объект, содержащий настройки опций.

    • cas (int: <optional>) - этот флаг требуется, если cas_required установлен в значение true либо в секрете, либо в конфигурации движка. Если не установлен, запись будет разрешена. Для успешной записи cas должен быть равен текущей версии секрета. Если равен 0, запись будет разрешена только если ключ не существует, так как неустановленные ключи не содержат информации о версии. Также помните, что мягкое удаление не удаляет данные о базовой версии из хранилища. Для записи в мягко удаленный ключ параметр cas должен соответствовать текущей версии ключа.

  • data (Map: <required>) - содержимое словаря, сохраненяемое и возвращемое при чтении.

Пример тела запроса:
{
  "options": {
    "cas": 0
  },
  "data": {
    "foo": "bar",
    "zip": "zap"
  }
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/secret/data/my-secret
Пример ответа:
{
  "data": {
    "created_time": "2025-07-30T11:24:18.377172189Z",
    "custom_metadata": {
      "owner": "jdoe",
      "mission_critical": "false"
    },
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  }
}

6. Исправление секрета

Эта конечная точка предоставляет возможность исправить существующий секрет в указанном местоположении. Секрет не должен быть ни удалён, ни уничтожен. Вызывающий токен должен иметь политику ACL, предоставляющую возможность исправления. В настоящее время поддерживается только JSON merge patch и должен быть указан с использованием значения заголовка Content-Type application/merge-patch+json. Новая версия будет создана после успешного применения исправления с предоставленными данными.

Метод Путь

PATCH

/:secret-mount-path/data/:path

6.1. Параметры

  • secret-mount-path (string: <required>) - путь к точке монтирования KV, содержащей используемый секрет, например, secret. Указывается как часть URL-адреса.

  • path (string: <required>) - указывает путь к используемому секрету. Указывается как часть URL-адреса.

  • options (Map: <optional>) - объект, содержащий настройки параметров.

    • cas (int: <optional>) - этот флаг обязателен, если cas_required имеет значение true либо в используемом секрете, либо в конфигурации движка. Для успешной записи cas должен быть установлен на текущую версию секрета. Операция патча должна быть предпринята для существующего ключа, поэтому указанное значение cas должно быть больше 0.

  • data (Map: <required>) - содержимое карты данных будет применено как частичное обновление к существующей записи посредством патча слияния JSON с существующей записью.

Пример тела запроса:
{
  "options": {
    "cas": 1
  },
  "data": {
    "foo": "a",
    "bar": {
      "baz": "b"
    }
  }
}
Пример запроса:
$ 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
Пример ответа:
{
  "data": {
    "created_time": "2025-07-30T11:21:03.703581595Z",
    "custom_metadata": {
      "owner": "jdoe",
      "mission_critical": "false"
    },
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  }
}

7. Чтение вложенных ключей

Эта конечная точка показывает вложенные ключи в секретной записи, существующей по запрошенному пути. Секретная запись по этому пути будет извлечена и лишена всех данных путем замены значений конечных ключей (т.е. ключей, не являющихся словарями, или ключей без вложенных ключей) на null.

Метод Путь

GET

/:secret-mount-path/subkeys/:path

7.1. Параметры

  • secret-mount-path (string: <required>) - путь к монтированию KV, содержащему секрет для чтения, например, secret. Указывается как часть URL.

  • path (string: <required>) - указывает путь к секрету для чтения. Указывается как часть URL.

  • version (int: 0) - указывает версию для возврата. Если не указано, возвращается последняя версия.

  • level (int: 0) - указывает максимальный уровень вложенности для вывода. Значение по умолчанию 0 не накладывает никаких ограничений. Если оно не равно нулю, ключи, находящиеся на указанном значении level, будут искусственно считаться листьями и, следовательно, будут null, даже если существуют другие подключи.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/secret/subkeys/my-secret?version=1
Пример секретных данных:
{
  "foo": "abc",
  "bar": {
    "baz": "def"
  },
  "quux": {}
}
Пример ответа:
{
  "subkeys": {
    "foo": null,
    "bar": {
      "baz": null
    },
    "quux": null
  },
  "metadata": {
    "created_time": "2025-07-30T11:21:03.703581595Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  }
}

8. Удаление последней версии секрета

Эта конечная точка инициирует мягкое удаление последней версии секрета в указанном месте. Это помечает версию как удалённую и предотвращает её возврат при чтении, но базовые данные не будут удалены. Удаление можно отменить, используя путь undelete.

Метод Путь

DELETE

/:secret-mount-path/data/:path

8.1. Параметры

  • secret-mount-path (string: <required>) - путь к ключу ключей Монтирование, содержащее секретный файл для удаления, например, secret. Указывается как часть URL-адреса.

  • path (string: <required>) - указывает путь к секретному файлу для удаления. Указывается как часть URL-адреса.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/secret/data/my-secret

9. Удаление версий секрета

Эта конечная точка выполняет мягкое удаление указанных версий секрета. Это помечает версии как удалённые и предотвращает их возврат при чтении, но базовые данные не будут удалены. Удаление можно отменить с помощью undelete path.

Метод Путь

POST

/:secret-mount-path/delete/:path

9.1. Параметры

  • secret-mount-path (string: <required>) - путь к точке монтирования KV, содержащей удаляемый секрет, например, secret. Указывается как часть URL-адреса.

  • path (string: <required>) - указывает путь к удаляемому секрету. Указывается как часть URL-адреса.

  • versions ([]int: <required>) - версии, которые нужно удалить. Версионированные данные не будут удалены, но больше не будут возвращаться в обычных get-запросах.

Пример тела запроса:
{
  "versions": [1, 2]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/secret/delete/my-secret

10. Восстановление версий секрета

Восстанавливает данные для указанной версии и пути в хранилище ключей и значений. Это восстанавливает данные, позволяя возвращать их в запросах GET.

Метод Путь

POST

/:secret-mount-path/undelete/:path

10.1. Параметры

  • secret-mount-path (строка: <required>) - путь к точке монтирования KV, содержащей секрет для восстановления, например, secret. Указывается как часть URL.

  • path (строка: <required>) - указывает путь к секрету для восстановления. Это указан как часть URL.

  • versions ([]int: <required>) - версии для восстановления. Версии будут восстановлены, а их данные будут возвращены в обычных запросах GET.

Пример тела запроса:
{
  "versions": [1, 2]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/secret/undelete/my-secret

11. Удаленипе секретных версий

Безвозвратно удаляет указанные данные версии для указанного ключа и номеров версий из хранилища ключей и значений.

Метод Путь

PUT

/:secret-mount-path/destroy/:path

11.1. Параметры

  • secret-mount-path (string: <required>) - путь к монтированию KV, содержащему секрет, который нужно удалить, например, secret. Указывается как часть URL.

  • path (string: <required>) - указывает путь к секрету, который нужно удалить. Указывается как часть URL.

  • versions ([]int: <required>) - версии, которые нужно удалить. Их данные будут удалены без возможности восстановления.

Пример тела запроса:
{
  "versions": [1, 2]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request PUT \
    --data @payload.json \
    https://127.0.0.1:8200/v1/secret/destroy/my-secret

12. Список секретов

Эта конечная точка возвращает список имён ключей в указанном месте. Папки добавляются суффиксом /. Входные данные должны быть папкой; список файлов не вернёт значение. Обратите внимание, что фильтрация на основе политик для ключей не применяется; не кодируйте конфиденциальную информацию в именах ключей. Сами значения недоступны через эту команду.

Эта конечная точка также поддерживает рекурсивный список (сканирование).

Метод Путь Информация

LIST

/:secret-mount-path/metadata/:path

Только keys.

SCAN

/:secret-mount-path/metadata/:path

Просто keys, рекурсивно.

LIST

/:secret-mount-path/detailed-metadata/:path

keys + key_info с полными метаданными.

SCAN

/:secret-mount-path/detailed-metadata/:path

keys + key_info с полными метаданными, рекурсивно.

Конечная точка detailed-metadata/:path позволяет пользователям просматривать полные метаданные для записей, на чтение которых у них может не быть разрешения. Предоставляйте доступ к этой конечной точке с осторожностью.

12.1. Параметры

  • after (string: "") - необязательный параметр для начала списка после пагинации; не обязательно.

  • limit (int: 0) - необязательное количество возвращаемых записей; по умолчанию все записи.

12.2. Параметры

  • secret-mount-path (string: <required>) - путь к точке монтирования KV, содержащей секрет для списка, например, secret. Указывается как часть URL-адреса.

  • path (string: <required>) - указывает путь к секретам для списка. Указывается как часть URL-адреса.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://127.0.0.1:8200/v1/secret/metadata/my-secret

В примере ниже показан вывод для пути запроса secret/, когда есть секреты в secret/foo и secret/foo/bar; обратите внимание на разницу в двух записях.

Пример ответа:
{
  "data": {
    "keys": ["foo", "foo/"]
  }
}

13. Чтение метаданных секрета

Эта конечная точка извлекает метаданные и версии секрета по указанному пути. Метаданные не зависят от версии.

Метод Путь

GET

/:secret-mount-path/metadata/:path

13.1. Параметры

  • secret-mount-path (string: <required>) - путь к точке монтирования KV, содержащей секрет для чтения, например, secret. Указывается как часть URL-адреса.

  • path (string: <required>) - указывает путь к секрету для чтения. Указывается как часть URL-адреса.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/secret/metadata/my-secret
Пример ответа:
{
  "data": {
    "cas_required": false,
    "created_time": "2025-07-30T11:21:03.703581595Z",
    "current_version": 3,
    "delete_version_after": "3h25m19s",
    "max_versions": 0,
    "oldest_version": 0,
    "updated_time": "2025-07-30T11:31:31.353765764Z",
    "custom_metadata": {
      "foo": "abc",
      "bar": "123",
      "baz": "5c07d823-3810-48f6-a147-4c06b5219e84"
    },
    "versions": {
      "1": {
        "created_time": "2025-07-30T11:21:03.703581595Z",
        "deletion_time": "",
        "destroyed": false
      },
      "2": {
        "created_time": "2025-07-30T11:24:18.377172189Z",
        "deletion_time": "",
        "destroyed": false
      },
      "3": {
        "created_time": "2025-07-30T11:31:31.353765764Z",
        "deletion_time": "",
        "destroyed": false
      }
    }
  }
}

14. Создание/обновление метаданных

Эта конечная точка создаёт или обновляет метаданные секрета в указанном месте. Новая версия не создаётся.

Метод Путь

POST

/:secret-mount-path/metadata/:path

14.1. Параметры

  • secret-mount-path (string: <required>) - путь к точке монтирования KV, содержащей секрет для обновления, например secret. Указывается как часть URL.

  • path (string: <required>) - указывает путь к секрету для обновления. Указывается как часть URL.

  • max_versions (int: 0) - количество версий, сохраняемых для каждого ключа. Если значение не задано, используется максимальная версия, заданная бэкендом. Как только количество версий ключа превысит разрешенное значение, самая старая версия будет удалена без возможности восстановления.

  • cas_required (bool: false) - если значение равно true, для ключа потребуется установка параметра cas для всех запросов на запись. Если значение равно false, будет использоваться конфигурация бэкенда.

  • delete_version_after (string:"0s") - установите значение delete_version_after на длительность, чтобы указать deletion_time для всех новых версий, записываемых в этот ключ. Если значение не задано, будет использоваться delete_version_after бэкенда. Если значение больше, чем delete_version_after бэкенда, будет использован delete_version_after бэкенда. Принимает формат длительности строки.

  • custom_metadata (map<string|string>: nil) - сопоставление произвольной строки со строковыми значениями предоставленных пользователем метаданных, предназначенное для описания секрета.

Пример тела запроса:
{
  "max_versions": 5,
  "cas_required": false,
  "delete_version_after": "3h25m19s",
  "custom_metadata": {
    "foo": "abc",
    "bar": "123",
    "baz": "5c07d823-3810-48f6-a147-4c06b5219e84"
  }
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/secret/metadata/my-secret

15. Метаданные исправления

Эта конечная точка исправляет существующую запись метаданных секрета в указанном местоположении. Вызывающий токен должен иметь политику ACL, предоставляющую возможность исправления. В настоящее время поддерживается только слияние JSON-патча, которое должно быть указано с использованием значения заголовка Content-Type application/merge-patch+json. Новая версия не создается.

Метод Путь

PATCH

/:secret-mount-path/metadata/:path

16. Параметры

  • secret-mount-path (string: <required>) - путь к точке монтирования KV, содержащей секрет для исправления, например secret. Указывается как часть URL.

  • path (string: <required>) - указывает путь к секрету для исправления. Указывается как часть URL.

  • max_versions (int: 0) - количество хранимых версий для каждого ключа. Если значение не задано, используется максимальная версия, заданная бэкендом. Как только количество версий ключа превысит установленное допустимое значение, самая старая версия будет удалена без возможности восстановления.

  • cas_required (bool: false) - если значение true, ключ потребует установки параметра cas для всех запросов на запись. Если значение false, будет использоваться конфигурация бэкенда.

  • delete_version_after (string:"0s") - установите значение delete_version_after на длительность, чтобы указать deletion_time для всех новых версий, записываемых в этот ключ. Если значение не задано, будет использоваться delete_version_after бэкенда. Если значение больше, чем delete_version_after бэкенда, будет использован delete_version_after бэкенда. Принимает формат длительности строки.

  • custom_metadata (map<string|string>: nil) - сопоставление произвольной строки со строковыми значениями предоставленных пользователем метаданных, предназначенное для описания секрета.

Пример тела запроса:
{
  "max_versions": 5,
  "custom_metadata": {
    "bar": "123"
  }
}
Пример запроса:
$ 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

17. Удаление метаданных и всех версий

Эта конечная точка безвозвратно удаляет метаданные ключа и все данные о версиях для указанного ключа. Вся история версий будет удалена.

Метод Путь

DELETE

/:secret-mount-path/metadata/:path

17.1. Параметры

  • secret-mount-path (string: <required>) - путь к монтированию KV, содержащему секретный ключ, который нужно удалить, например, secret. Указывается как часть URL-адреса.

  • path (string: <required>) - указывает путь к секретному ключу, который нужно удалить. Указывается как часть URL-адреса.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/secret/metadata/my-secret