--- title: "Using the Secret Manager with the HashiCorp Vault KV2-compliant API" description: "- An OVHcloud customer account" url: https://docs.us.ovhcloud.com/en/manage-and-operate/secret-manager/kv2-api lang: en --- > For AI agents: the complete documentation index is available at https://docs.us.ovhcloud.com/en/llms.txt, the full documentation bundle is available at https://docs.us.ovhcloud.com/en/llms-full.txt. # Using the Secret Manager with the HashiCorp Vault KV2-compliant API ## Requirements - An [OVHcloud customer account](https://docs.us.ovhcloud.com/en/account/account-information/create-account.md) - Have [ordered an OKMS domain](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/quick-start.md) or [created a first secret](https://docs.us.ovhcloud.com/en/manage-and-operate/secret-manager/use-secret-manager.md)   ## Instructions ### Description The Secret Manager is a product that allows you to securely store credentials, API keys, SSH keys, or any other type of secret necessary for the operation of your applications. A secret is a collection of one or more key-value pairs grouped within a version. Each modification of a secret creates a new version of that secret, allowing you to go back in the history of changes to the secret. The HashiCorp Vault KV2 compliant APIs are one of the two API sets offered by the Secret Manager, along with the [REST API](https://docs.us.ovhcloud.com/en/manage-and-operate/secret-manager/rest-api.md). They are designed to be similar to HashiCorp Vault APIs to ensure compatibility with applications already compatible with HashiCorp Vault.   ### Contacting the OKMS domain Communication with the OKMS domain for encryption and signature actions is available via APIs. Since the OKMS domain is regionalized, you can access the API directly in its region: `https://my-region.okms.ovh.us`. For example, for an OKMS domain created in the **us-east-vin** region: [https://us-east-vin.okms.ovh.us](https://us-east-vin.okms.ovh.us/). It's possible to communicate with the OKMS domain using: - The Swagger UI - The OMKS CLI: [https://github.com/ovh/okms-cli](https://github.com/ovh/okms-cli) - The Golang SDK: [https://pkg.go.dev/github.com/ovh/okms-sdk-go](https://pkg.go.dev/github.com/ovh/okms-sdk-go)   ### Using the OKMS domain API via the Swagger UI You can access the OKMS domain Swagger UI by clicking on the link in the [OVHcloud Control Panel](https://manager.us.ovhcloud.com/), in your OKMS domain dashboard. You will land on the non-authenticated version of the Swagger UI, which is meant for API documentation purposes. If you want to use the Swagger UI to make requests on your own OKMS domain, you will need to switch to the authenticated version, which is linked in the description section: The next steps will guide you on how to authenticate.   #### Importing your OKMS domain credentials into the browser **Warning:** **NOTE:** Unless you are confident in your IAM configuration, we suggest using a KMS access certificate that is not tied to a specific user. If you are uncertain, you can toggle the `Add account root identity` slider when [generating your access certificate](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/okms-certificate-management.md). This process is covered in the [Importing your KMS credentials into the browser](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/use-key-management-service.md#importing-your-kms-credentials-into-the-browser) section of our [Using OVHcloud Key Management Service (KMS)](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/use-key-management-service.md) guide.   #### Accessing the authenticated Swagger UI This process is covered in the [Accessing the authenticated Swagger UI](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/use-key-management-service.md#accessing-the-authenticated-swagger-ui) section of our [Using OVHcloud Key Management Service (KMS)](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/use-key-management-service.md) guide.   ### Create a Secret To create a secret, you can use the following API: | **Method** | **Path** | **Description** | | ---------- | ------------------------------------- | --------------- | | POST | /api/\{okmsId}/v1/secret/data/\{path} | Create a Secret | The secret's path must be specified in the API path. The API expects the following values: | **Field** | **Value** | **Description** | | --------- | --------- | -------------------------------------------------- | | data | Json | Secret content; it is possible to have nested JSON | | cas | Integer | (optional) Current version of the secret | For example: ``` { "data": { "login": "admin", "password": "my_secret_password", "address": { "ip": "1.1.1.1" }, "ports": [ "30", "31" ] }, "options": { "cas": 0 } } ``` It is also possible to add metadata to the secret via the API: | **Method** | **Path** | **Description** | | ---------- | ----------------------------------------- | ---------------------- | | POST | /api/\{okmsId}/v1/secret/metadata/\{path} | Update secret metadata | The API expects the following values: | **Field** | **Value** | **Description** | | -------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | cas\_required | boolean | If enabled, it is necessary to systematically specify the current version number when making changes | | custom\_metadata | Json | Additional data associated with the secret. This data is not protected by the secret | | deactivate\_version\_after | [Duration String](https://developer.hashicorp.com/vault/docs/concepts/duration-format) | Duration after which versions are deactivated | | max\_versions | Integer | Maximum number of versions for the secret | For example: ``` { "cas_required": true, "custom_metadata": { "project": "A", "team": "X" }, "deactivate_version_after": "10h30m10s", "max_versions": 5 } ```   ### Manage Secrets #### Update Metadata and configuration Once the secret is created, it is possible to update the secret's metadata or configuration. | **Method** | **Path** | **Description** | | ---------- | ----------------------------------------- | ---------------------- | | PATCH | /api/\{okmsId}/v1/secret/metadata/\{path} | Update secret metadata | The API expects the following values: | **Field** | **Value** | **Description** | | -------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | cas\_required | boolean | If enabled, it is necessary to systematically specify the current version number when making changes | | custom\_metadata | Json | Additional data associated with the secret. This data is not protected by the secret | | deactivate\_version\_after | [Duration String](https://developer.hashicorp.com/vault/docs/concepts/duration-format) | Duration after which versions are deactivated | | max\_versions | Integer | Maximum number of versions for the secret | It is also possible to change the default configuration of the OKMS domain for the values **cas\_required**, **deactivate\_version\_after**, and **max\_versions** using the API: | **Method** | **Path** | **Description** | | ---------- | ------------------------------- | ------------------------------------------------ | | POST | /api/\{okmsId}/v1/secret/config | Set the default configuration of the OKMS domain |   #### Update the Secret's data This call will change the secret's data but will preserve the Version ID: | **Method** | **Path** | **Description** | | ---------- | ------------------------------------- | --------------- | | PATCH | /api/\{okmsId}/v1/secret/data/\{path} | Update a secret |   #### Create a new version You can create a new version, based on the most recent Version ID, using the API: | **Method** | **Path** | **Description** | | ---------- | ------------------------------------- | --------------- | | POST | /api/\{okmsId}/v1/secret/data/\{path} | Update a secret | A secret can contain as many versions as desired, up to the maximum limit of the **max\_versions** parameter. If the maximum number of versions is reached, the oldest version is automatically deleted.   #### Manage versions It is possible to manage the different versions of the secret using the API: | **Method** | **Path** | **Description** | | ---------- | --------------------------------------- | ------------------------------------------------ | | POST | /api/\{okmsId}/v1/secret/delete/\{path} | Deactivates the specified versions of the secret | | DELETE | /api/\{okmsId}/v1/secret/data/\{path} | Deactivates the latest version of the secret | Deactivated versions of a secret are still present in the Secret Manager, but their content is no longer accessible. It is possible to reactivate a version via the API: | **Method** | **Path** | **Description** | | ---------- | ----------------------------------------- | ------------------------------------------------ | | POST | /api/\{okmsId}/v1/secret/undelete/\{path} | Reactivates the specified versions of the secret | Finally, it is possible to permanently delete a version via the API: | **Method** | **Path** | **Description** | | ---------- | ---------------------------------------- | -------------------------------------------- | | PUT | /api/\{okmsId}/v1/secret/destroy/\{path} | Deletes the specified versions of the secret | It's also possible to permanently delete the whole secret with all his versions: | **Method** | **Path** | **Description** | | ---------- | ----------------------------------------- | --------------------------------------- | | DELETE | /api/\{okmsId}/v1/secret/metadata/\{path} | Deletes the secret and all his versions | **Warning:** **NOTE:** A deleted version is no longer present in the Secret Manager and cannot be reactivated.   ## Go further Browse all the [Secret Manager guides](https://docs.us.ovhcloud.com/en/manage-and-operate/secret-manager/landing-page-secret-manager.md). Browse the rest of the [OVHcloud US documentation](https://docs.us.ovhcloud.com/en/index.md) for guides on our other products and services. Learn more about [Secret Manager](https://us.ovhcloud.com/identity-security-operations/secret-manager/) on the OVHcloud US website.