Managing key-value secrets with Vault API

With IBM Cloud® Secrets Manager, you can manage multiple versions per key and access the history and metadata of your key-value secret by using the HashiCorp Vault HTTP API.

Overview

If you already use the Vault API, you can use its API format and guidelines to interact with Secrets Manager. Secrets Manager supports KV version 2 only. The endpoints for the key-value secrets engine that are defined in the Vault documentation are compatible with the CLI and other applicable tools.

For more information about authentication and the custom version of open source HashiCorp Vault that Secrets Manager uses, see Vault API.

To use the standard REST API for Secrets Manager, check out the Secrets Manager API reference.

Difference between KV and Secrets Manager

The key-value secrets engine that Secrets Manager uses differs slightly from Vault's KV secrets engine.

You cannot fully customize the path. The path to a key-value secret must be:
- {secret_group_id}/{secret_name} for secrets that are located in a custom secret group.
- /{secret_name} for secrets that are in the default group.
The methods that are used on Vault to configure the key-value engine and read the configuration are not supported.

Create or update a key-value secret

Create a version of a key-value secret.

Example request

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

Table 1. Create or update a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.
`data`	Required. The secret data in JSON format to assign to the secret. The maximum file size is 512 KB.

Example response

A request to update a key-value secret in the default secret group returns the following response:

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Read a version of a key-value secret

Get a version of a key-value secret. A successful request returns the secret data that is associated with the specified version of your secret, along with other metadata.

Example request

curl -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}?version={version}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

Table 2. Read a version of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`version`	The versions that you want to read.
`Vault-Token`	The authentication token that is retrieved from Vault.

Example response

A request to get a version of a key-value secret in the default secret group returns the following response:

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "data": {
            "key": "value"
        },
        "metadata": {
            "created_time": "2022-01-13T21:31:49.893962888Z",
            "deletion_time": "",
            "destroyed": false,
            "version": 1
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Delete the latest version of a key-value secret

Delete the latest version of a key-value secret. After you delete the version, you cannot retrieve it by using list or get API calls. However, it is a soft delete and the underlying data is not removed. You can undo the deletion by calling the undelete API endpoint.

Example request

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

Table 3. Delete the latest version of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.

Example response

A request to delete the latest version of a key-value secret in the default secret group returns a blank response with a 204 status code to confirm that the latest version was deleted.

Delete specified versions of a key-value secret

Delete the specified versions of a key-value secret. After you delete the versions, you can't retrieve them by using list or get API calls. However, it is a soft delete and the underlying data is not removed. You can undo the deletion by calling the undelete API endpoint.

Example request

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/delete/test-kv' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -d '{
            "versions": [1, 2]
            }'

Table 4. Delete specified versions of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.
`versions`	The specified versions that are to be deleted.

Example response

A request to get delete specified versions of a key-value secret in the default secret group returns the following response:

{
    "request_id": "43abde16-6a33-971f-1690-469eccc00d91",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Undelete a key-value secret

Restore a previously deleted version of a key-value secret.

Example request

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/undelete/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [
                1, 2
                ]
            }

Table 5. Undelete a version of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.
`versions`	The versions of the key-value secret you want to delete.

Example response

A request to restore a version of a key-value secret in the default secret group returns a blank response with a 204 status code to confirm that the specified versions were restored.

Destroy versions of a secret

Destroy specified versions of a key-value secret permanently. To soft delete versions of a secret instead, use the delete specified versions API endpoint.

Example request

curl -X POST 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/destroy/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [1, 3]
            }'

Table 6. Destroy versions of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.
`versions`	The versions of the key-value secret you want to permanently destroy.

Example response

A request to permanently destroy versions of a key-value secret in the default secret group returns a blank response with a 204 status code to confirm that the secret's versions were destroyed.

Create or update key-value secret metadata

Create or update the metadata of a key-value secret, such as the maximum number of versions or other custom values. To update the actual contents of the secret, use the Create or update a secret method.

Example request

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "custom_metadata": {
                "meta1": "data1",
                "meta2": "data2"
                }
            }'

Table 7. Update the metadata of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.

Example response

A request to update the metadata of a key-value secret in the default secret group returns a blank response with a 204 status code to confirm that the secret's metadata was updated.

Read metadata of key-value secret

Get a key-value secret's metadata by specifying the ID of the version.

Example request

curl -X GET 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

Table 8. Read the metadata of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.

Example response

A request to get the metadata of a key-value secret in the default secret group returns the following response:

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "cas_required": false,
        "created_time": "2022-01-13T21:31:49.893962888Z",
        "current_version": 3,
        "custom_metadata" : {
              "meta1": "data1",
              "meta2": "data2"    
        },
        "delete_version_after": "0s",
        "max_versions": 0,
        "oldest_version": 0,
        "updated_time": "2022-02-09T23:54:16.313286558Z",
        "versions": {
            "1": {
                "created_time": "2022-01-13T21:31:49.893962888Z",
                "deletion_time": "",
                "destroyed": false
            },
            "2": {
                "created_time": "2022-02-09T23:41:58.888138788Z",
                "deletion_time": "",
                "destroyed": false
            },
            "3": {
                "created_time": "2022-02-09T23:54:16.313286558Z",
                "deletion_time": "",
                "destroyed": false
            }
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Delete the metadata and all versions of a key-value secret

Delete the metadata and all version data of a specified key-value secret permanently. All version history is removed when you use this API endpoint.

Example request

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

Table 9. Delete the metadata of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.

Example response

A request to delete the metadata and all versions of a key-value secret in the default secret group returns the following response:

{
    "request_id": "62b1e2c2-801a-6592-0526-edb38896a546",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

List key names of a key-value secret

Get a list of key names of a key-value secret. Do not encode sensitive information in key names. The values of the keys are not accessible by using this command.

In {sm-short}, you can't use the LIST HTTP verb to get the list of key names. You can do so only in Vault's KV API.

Example request

curl -X GET "https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/?list=true" \ 
    -H 'Accept: application/json'\
    -H 'X-Vault-Token: {Vault-Token}'

Table 10. List the key names of a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`Vault-Token`	The authentication token that is retrieved from Vault.

Example response

A request to list the key names of a key-value secret in the default secret group returns the following response:

{
    "request_id": "a21993df-a4b7-21f1-95a9-c1af7be87d1b",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "keys": [
            "secret1",
            "secret2"
        ]
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Patch a key-value secret

Update an existing key-value secret by providing only the details that you want to change. When you patch a secret, a new version is created. Any data that you don't change remains exactly as it is in the previous version of the secret.

Example request

curl -X PATCH 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

Table 11. Create or update a key-value secret request parameters
Request parameter	Description
`instance_id`	The ID of the Secrets Manager instance.
`region`	The region in which the Secrets Manager instance was created.
`secret_name`	The name of the key-value secret.
`Vault-Token`	The authentication token that is retrieved from Vault.
`data`	Required. The secret data in JSON format to patch the secret with. The maximum file size is 512 KB.

Example response

A request to update a key-value secret in the default secret group returns the following response:

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}