Unified Key Orchestrator API for IBM Cloud Hyper Protect Crypto Services

Introduction

Last updated: 2024-06-05

IBM Cloud Hyper Protect Crypto Services is a dedicated key management service and hardware security module (HSM). It is designed to enable you to take control of your cloud data encryption keys and cloud hardware security models, and is the only service in the industry built on FIPS 140-2 Level 4-certified hardware. Unified Key Orchestrator is a public cloud control plane for multicloud and hybrid cloud key orchestration. As part of Hyper Protect Crypto Services, Unified Key Orchestrator provides key lifecycle management according to NIST recommendations and secure transfer of keys to internal keystores in the service instance or external keystores.

For more information about using Hyper Protect Crypto Services, see the IBM Cloud docs.

The code examples on this tab use the client library that is provided for Go.

go get -u github.com/IBM/ibm-hpcs-uko-sdk

GitHub

https://github.com/IBM/ibm-hpcs-uko-sdk

Endpoint URLs

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. When you call the API, use the URL that corresponds to the region where your service instance is deployed.

Dallas: https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/
Frankfurt: https://eu-de.broker.hs-crypto.cloud.ibm.com/crypto_v2/
London: https://eu-gb.broker.hs-crypto.cloud.ibm.com/crypto_v2/
Madrid: https://eu-es.broker.hs-crypto.cloud.ibm.com/crypto_v2/
São-Paulo: https://br-sao.broker.hs-crypto.cloud.ibm.com/crypto_v2/
Tokyo: https://jp-tok.broker.hs-crypto.cloud.ibm.com/crypto_v2/
Toronto: https://ca-tor.broker.hs-crypto.cloud.ibm.com/crypto_v2/
Washington DC:https://us-east.broker.hs-crypto.cloud.ibm.com/crypto_v2/

To call other API methods, use the endpoint URL that is returned in the uko section when you call the Retrieve the API endpoint URL method. The returned URL contains the region and port information. Note the URLs vary depending on whether you are using the public or private endpoint.

If you create your instances after April 12 2024 in certain regions, you might need to use the new API endpoints with the new format as <INSTANCE_ID>.uko.<REGION>.hs-crypto.appdomain.cloud. The availability date varies by region. For more information about the supported regions, the availability dates, and the new endpoint URLs, see New endpoints.

"public": "uko.<region>.hs-crypto.cloud.ibm.com:<port>"
"private": "uko.private.<region>.hs-crypto.cloud.ibm.com:<port>"

Authentication

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Managing access for Hyper Protect Crypto Services.

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token and instance ID in API requests.

You can build your API request by pairing a service endpoint with your authentication credentials:

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys' \
    --header 'Authorization: Bearer <access_token>' \ 
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \ 
    --header 'UKO-Vault: <vault_ID>'

Replace <region> with the prefix that represents the geographic area where your service instance resides. For more information, see Regions and locations.
Replace <port> with the port number of the API endpoint.
Replace <access_token> with your Cloud IAM token.
Replace <vault_ID> with the ID of the vault that your keys are assigned to.

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see Retrieving an access token programmatically.

To find out more about setting up the Hyper Protect Crypto Services key management service API, see Accessing the Unified Key Orchestrator API.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Unified Key Orchestrator API.

The SDK provides client configuration initialization method in which you will need to replace instance URL with a service endpoint, the api_key with the API key associated with your application. Use the client configuration options in the method to create a new Unified Key Orchestrator client. The method handles the authentication procedure with the provided API key.

To retrieve your access token:

curl -X POST "https://iam.cloud.ibm.com/identity/token"   -H "Content-Type: application/x-www-form-urlencoded"   -H "Accept: application/json"   -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>" > token.json
Copy to clipboard

Replace <API_KEY> with your service credentials. Then use the full access_token value, prefixed by the _Bearer_token type, to authenticate your API requests.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --output JSON

Replace <instance_name> with the unique alias that you assigned to your Hyper Protect Crypto Services instance. The GUID value in the JSON output represents the instance ID for the service.

To authenticate to Hyper Protect Crypto Services Unified Key Orchestrator API:

package main

import (
    "fmt"

    "github.com/IBM/go-sdk-core/core"
    "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

    apikey := "<api_key>"
    // for staging "https://iam.test.cloud.ibm.com"
    iamurl := "https://iam.cloud.ibm.com"

    token, err := ukov4.GetToken(apikey, iamurl)

    if err != nil {
        fmt.Println("Error fetching the token")
        return
    }

    authenticator, err := core.NewBearerTokenAuthenticator(token)

    if err != nil {
        fmt.Println("Error assigning the token to authenticator")
        return
    }

    options := ukov4.UkoV4Options{
        Authenticator: authenticator,
        // default to the contextual url, it may be overridden by an environment variable
        URL: "<instance_url>",
    }

    uko, err := ukov4.NewUkoV4UsingExternalConfig(&options)

    if err != nil {
        fmt.Println("Error creating UkoV4 client")
        return
    }

}
Copy to clipboard

Replace <api_key> with your service credentials. Then use the full access_token value, prefixed by the _Bearer_token type, to authenticate your API requests.

Replace <instance_url> with your instance API endpoint URL.

Auditing

You can monitor API activity within your account by using the Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track Hyper Protect Crypto Services activity, see Auditing Events for Hyper Protect Crypto Services with Unified Key Orchestrator.

Error handling

Hyper Protect Crypto Services uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Status code summary
Status code	Description
200 OK	Everything worked as expected.
201 OK	Everything worked as expected. No content.
400 Bad Request	The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized	The parameters were valid but the request failed due insufficient permissions.
404 Not Found	The requested resource doesn't exist.
410 Gone	The requested resource was deleted and no longer exists.
429 Too Many Requests	Too many requests hit the API too quickly.
500 Server Error	Something went wrong on the end of the Hyper Protect Crypto Services instance.

Metadata

When you create or store keys in Hyper Protect Crypto Services, you can attach key-value data to your resources for easy identification of your keys.

The name, description, and tag parameters are useful for storing information on your resources. For example, you can store corresponding unique identifiers from your app or system on a Hyper Protect Crypto Services key.

To protect your privacy, do not store any personally identifiable information, such as your name or location, as metadata for your keys.

Change log

Important changes, such as additions, updates, and breaking changes, are marked with a change notice in this reference.

For a complete list of changes and improvements to this API, see the Hyper Protect Crypto Services Unfied Key Orchestrator API change log.

List all managed keys in the instance. It is possible to sort by the following parameters: label, algorithm, state, activation_date, deactivation_date, created_at, updated_at, size, vault.id.

GET /v4/managed_keys

Request

Custom Headers

Accept
string
Allowable values: [application/json,application/vnd.ibm.uko.managed-key-list.v4.1+json,application/vnd.ibm.uko.managed-key-list.v4.1.json+zip]

Query Parameters

vault.id
string[]
The UUID of the Vault.

Possible values: length = 36, Value must match regular expression ^[-0-9a-z]+$
algorithm
string[]
The algorithm of a returned key.

Allowable values: [aes,rsa,hmac,ec,des,dilithium]
state
string[]
The state that returned keys are to be in.

Allowable values: [pre_activation,active,deactivated,destroyed,compromised,destroyed_compromised]
Default: ["pre_activation","active"]
limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["-updated_at"]
label
string
The label of the key

Possible values: Value must match regular expression ^[A-Za-z0-9._ /-]+$
activation_date
string
Return only managed keys whose activation_date matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
activation_date_min
string
Return only managed keys whose activation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'activation_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
activation_date_max
string
Return only managed keys whose activation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'activation_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date
string
Return only managed keys whose deactivation_date matches the parameter. This query parameter cannot be used in conjunction with the 'expiration_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date_min
string
Return only managed keys whose deactivation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'expiration_date_min' and 'expiration_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date_max
string
Return only managed keys whose deactivation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'expiration_date_min' and 'expiration_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date
string
Return only managed keys whose deactivation_date matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date_min
string
Return only managed keys whose deactivation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'deactivation_date_min' and 'deactivation_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date_max
string
Return only managed keys whose deactivation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'deactivation_date_min' and 'deactivation_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at
string
Return only managed keys whose created_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_min
string
Return only managed keys whose created_at is at or after the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_max
string
Return only managed keys whose created_at is at or before the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at
string
Return only managed keys whose updated_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_min
string
Return only managed keys whose updated_at is after the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_max
string
Return only managed keys whose updated_at is before the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
rotated_at_min
string
Return only managed keys whose rotated_at is after the parameter value.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
rotated_at_max
string
Return only managed keys whose rotated_at is before the parameter value.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
size
string
The size of the key
size_min
string
The minimum size of the key. This query parameter cannot be used in conjunction with the 'size' query parameter.
size_max
string
The maximum size of the key. This query parameter cannot be used in conjunction with the 'size' query parameter.
referenced_keystores[].type
string[]
Type of referenced keystore. This query parameter cannot be used in conjunction with the 'instances[].keystore.type' query parameter.

Allowable values: [aws_kms,azure_key_vault,google_kms,ibm_cloud_kms,cca]
referenced_keystores[].name
string[]
Name of referenced keystore

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
instances[].keystore.type
string[]
Type of keystore supported by one of the instances. This query parameter cannot be used in conjunction with the 'referenced_keystores[].type' query parameter.

Allowable values: [aws_kms,azure_key_vault,google_kms,ibm_cloud_kms,cca]
template.name
string
Return only managed keys whose template name begins with the string.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
Example: AWS-TEMPLATE
template.id
string[]
Return only managed keys with the given template UUID.

Possible values: length = 36, Value must match regular expression ^[-0-9a-z]+$
template.type[]
string[]
Return only managed keys with the given template type.

Allowable values: [user_defined,shadow]

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  listManagedKeyOptions := ukov4.ListManagedKeysOptions{
    Limit:  core.Int64Ptr(2),
    Offset: core.Int64Ptr(0),
  }
  listKeys, _, _ := uko.ListManagedKeys(&listManagedKeyOptions)
  b, _ := json.MarshalIndent(listKeys, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKeyList listManagedKeys() {
    // Initialize the uko client/uko service as specified in Authentication

    ServiceCall<ManagedKeyList> managedKeyListServiceCall = ukoService.listManagedKeys();
    Response<ManagedKeyList> managedKeyListResponse = managedKeyListServiceCall.execute();
    ManagedKeyList result = managedKeyListResponse.getResult();
    return result;
}                       
Copy to clipboard

Response

Response Body

managedKeyList

The base schema for listing managed keys.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.

Example responses

Status 200

{
  "total_count": 4,
  "limit": 20,
  "offset": 100,
  "first": {
    "href": "/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0'"
  },
  "last": {
    "href": "/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0"
  },
  "managed_keys": [
    {
      "id": "35f690df-064a-4758-8694-b2f011810701",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-1",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "6393e930-562c-4042-b324-45c37d3d49d9",
        "name": "AZURE-template-920",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/6393e930-562c-4042-b324-45c37d3d49d9"
      },
      "version": "1,",
      "description": "AZURE KEY",
      "label": "AZUREproduction2029",
      "state": "active",
      "size": "2048",
      "algorithm": "rsa",
      "verification_patterns": [
        {
          "method": "PUB-HASH-SHA-1",
          "value\"": "947AA69D48EEE487048AF2999DADB8DA55769529"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "AZURE"
        },
        {
          "name": "ENV",
          "value": "production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AZURE-TAG"
        }
      ],
      "created_at": "2023-06-05T11:33:54.000Z",
      "updated_at": "2023-06-05T11:33:54.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "keystore": [
            {
              "id": "2e124fa5-9ef6-406c-bb2f-9ad049ff1073",
              "name": "Azure Keystore",
              "type": "azure_key_vault",
              "href": "v4/managed_keys/3dab42dc-6941-4841-8d27-4dabcc5aa09e"
            }
          ]
        }
      ],
      "instances": [
        {
          "id": "acb332dd-216c-44dd-8593-02bd2119ec62",
          "label_in_keystore\"": "AZUREproduction2029",
          "keystore": {
            "group": "Production AZURE GB",
            "type": "azure_key_vault"
          },
          "azure_key_protection_level": "software"
        }
      ],
      "href": "/v4/managed_keys/35f690df-064a-4758-8694-b2f011810701",
      "status_in_keystores": [
        {
          "keystore": [
            {
              "id": "2e124fa5-9ef6-406c-bb2f-9ad049ff1073",
              "name": "Azure Keystore",
              "type": "azure_key_vault",
              "href": "v4/managed_keys/3dab42dc-6941-4841-8d27-4dabcc5aa09e"
            }
          ],
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "d1e2525c-62c8-4df2-9173-69e1a7bc8cdb/d1e2525c-62c8-4df2-9173-69e1a7bc8cdb"
        }
      ]
    },
    {
      "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "EXAMPLE-VAULT",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
        "name": "AWS-EXAMPLE-TEMPLATE",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
      },
      "version": 1,
      "description": "AWS key template description",
      "label": "AWS-production-2029",
      "state": "active",
      "size": 256,
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method\"": "ENC-ZERO",
          "value": "C05CA1"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "AWS"
        },
        {
          "name": "ENV",
          "value": "production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AWS-TAG"
        }
      ],
      "created_at": "2023-06-05T10:40:13.000Z",
      "updated_at": "2023-06-05T10:40:19.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "0743ae15-c594-476d-8e9a-1564740ace53",
          "name": "AWS KMS Keystore 335",
          "type": "aws_kms",
          "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
        }
      ],
      "instances": [
        {
          "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
          "label_in_keystore": "AWS-production-2029",
          "type": "secret_key",
          "keystore": {
            "group\"": "Production-AWS-DE",
            "type\"": "aws_kms"
          }
        }
      ],
      "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "0743ae15-c594-476d-8e9a-1564740ace53",
            "name": "AWS KMS Keystore 335",
            "type": "aws_kms",
            "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
        }
      ]
    },
    {
      "id": "0beedc06-4608-48ae-8ae3-8b7bf3c2c39f",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-2",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "64f98479-392d-4af2-a076-77cc21b8c6f3",
        "name": "IBM-CLOUD-TEMPLATE",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/64f98479-392d-4af2-a076-77cc21b8c6f3"
      },
      "version": 1,
      "description": "",
      "label": "IBMCloudProduction2029",
      "state": "active",
      "size": "256",
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method": "ENC-ZERO",
          "value": "4ADDCB"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "IBMCloud"
        },
        {
          "name": "ENV",
          "value": "Production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AWS-TAG"
        }
      ],
      "created_at": "2023-06-05T11:59:47.000Z",
      "updated_at": "2023-06-05T11:59:47.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "0743ae15-c594-476d-8e9a-1564740ace53",
          "name": "IBM CLOUD KEYSTORE",
          "type": "ibm_cloud_kms",
          "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
        }
      ],
      "instances": [
        {
          "id": "0c5b14ea-a3dd-407c-af7c-fd74575ccbad",
          "label_in_keystore": "IBMCloudProduction2029",
          "type": "secret_key",
          "keystore": {
            "group": "Production External GB",
            "type": "ibm_cloud_kms"
          }
        }
      ],
      "href": "/v4/managed_keys/0beedc06-4608-48ae-8ae3-8b7bf3c2c39f",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "0743ae15-c594-476d-8e9a-1564740ace53",
            "name": "IBM CLOUD KEYSTORE",
            "type": "ibm_cloud_kms",
            "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "804854d0-4eb7-416e-8ae2-45ba56921c8a/804854d0-4eb7-416e-8ae2-45ba56921c8a"
        }
      ]
    },
    {
      "id": "d7b8204c-4f8f-4ba1-b306-5434ae817f51",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-3",
        "href": "v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "09d229e5-e330-4e85-a7ee-cc8555d38603",
        "name": "GOOGLE-TEMPLATE-86",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/09d229e5-e330-4e85-a7ee-cc8555d38603"
      },
      "version": 1,
      "description": "Google Key",
      "label": "Google-Production-2029",
      "state": "active",
      "size": "256",
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method\"": "ENC-ZERO",
          "value": "C3F432"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "Google"
        },
        {
          "name": "ENV",
          "value": "Production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "Google-TAG"
        }
      ],
      "created_at": "2023-06-05T13:18:28.000Z",
      "updated_at": "2023-06-05T13:18:28.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "6e026faa-d44d-4a1a-aeea-0e1ef2840cba",
          "name": "Google Keystore",
          "type": "google_kms",
          "href": "/v4/keystores/6e026faa-d44d-4a1a-aeea-0e1ef2840cba"
        }
      ],
      "instances": [
        {
          "id": "ed74a984-2057-484c-9198-54839f3fec62",
          "label_in_keystore": "Google-Production-2029",
          "type": "secret_key",
          "keystore": {
            "group": "Production Google",
            "type": "google_kms"
          },
          "google_key_protection_level": "software",
          "google_key_purpose": "encrypt_decrypt",
          "google_kms_algorithm": "google_symmetric_encryption"
        }
      ],
      "href": "/v4/managed_keys/d7b8204c-4f8f-4ba1-b306-5434ae817f51",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "6e026faa-d44d-4a1a-aeea-0e1ef2840cba",
            "name": "Google Keystore",
            "type": "google_kms",
            "href": "/v4/keystores/6e026faa-d44d-4a1a-aeea-0e1ef2840cba"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "projects/plated-field-364019/locations/europe-west3/keyRings/uko-ring/cryptoKeys/ROBOT-Google-Key-05-06-nciYX/cryptoKeyVersions/1"
        }
      ]
    }
  ],
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  }
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Creates a new key based on the supplied template. The template must exist in the system prior to this call.

POST /v4/managed_keys

Request

Request Body

Required*

keyCreationRequest

Parameters required to create a key

Examples:

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --data-raw '{
        "template_name": "<template_name>",
        "label": "managed-key",
        "description": "new description"
        "vault": {
            "id": "vault_uuid"
        },
        "tags": [
            {
                "name": "first-tag",
                "value": "for-IBM-CLOUD"
            }
        ]
}'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4ManagedKeyOptions := ukov4.CreateManagedKeyOptions{
    UKOVault:     core.StringPtr("<vault_id>"),
    TemplateName: core.StringPtr("<template_name>"),
    Vault: &ukov4.VaultReferenceInCreationRequest{
      ID: core.StringPtr("<vault_id>"),
    },
    Label: core.StringPtr("<label>"),
  }

  managedKey, _, _ := uko.CreateManagedKey(&ukov4ManagedKeyOptions)

  b, _ := json.MarshalIndent(managedKey, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey createMangedKey(String id) {
    // Initialize the uko client/uko service as specified in Authentication
    
    VaultReferenceInCreationRequest vaultReferenceInCreationRequest = 
             new VaultReferenceInCreationRequest.Builder()
             .id(id)
             .build();
    CreateManagedKeyOptions createManagedKeyOptions =
            new CreateManagedKeyOptions.Builder()
            .templateName("IBM-CLOUD-KMS-AES-d6d409f224de")
            .vault(vaultReferenceInCreationRequest)
            .label("label")
            .build();
    ServiceCall<ManagedKey> managedKey = ukoService.createManagedKey(createManagedKeyOptions);
    Response<ManagedKey> managedKeyResponse = managedKey.execute();
    return managedKeyResponse.getResult();
  }   
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

201
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
409
Key with a given label already exists.
424
One or more keystores defined by the keystore tag is not available. Inspect response body for details.

Example responses

Status 201

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 424

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Delete a managed key by ID from the vault. A key must be in a 'destroyed' state for it to be eligible for deletion.

DELETE /v4/managed_keys/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request DELETE 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication


  ukov4ManagedKeyOptions := ukov4.DeleteManagedKeyOptions{
    ID:       core.StringPtr("<managed_key_id>"),
    IfMatch:  core.StringPtr("<ETag>")
  }

  managedKey, _ := uko.DeleteManagedKey(&ukov4ManagedKeyOptions)

  fmt.Println(managedKey.StatusCode)

}
Copy to clipboard

Example request

public static int deleteManagedKey(String id, String vaultId, String etag) {
    // Initialize the uko client/uko service as specified in Authentication

    DeleteManagedKeyOptions deleteManagedKeyOptions = 
              new DeleteManagedKeyOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .build();
    ServiceCall<Void> voidServiceCall = ukoService.deleteManagedKey(deleteManagedKeyOptions);
    Response<Void> response = voidServiceCall.execute();
    return response.getStatusCode(); //status code should be 204
}
Copy to clipboard

Response

Status Code

204
Deletion successful
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.

Example responses

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Retrieve a managed key and its details by specifying the ID.

GET /v4/managed_keys/{id}

Request

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication


  ukov4ManagedKeyOptions := ukov4.GetManagedKeyOptions{
    ID:       core.StringPtr("<managedkey_id>")
  }

  managedKey, _, _ := uko.GetManagedKey(&ukov4ManagedKeyOptions)

  b, _ := json.MarshalIndent(managedKey, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey getManagedKey(String id, String vaultId) {
    // Initialize the uko client/uko service as specified in Authentication
    GetManagedKeyOptions getManagedKeyOptions =
            new GetManagedKeyOptions.Builder()
            .id(id)
            .build();
    ServiceCall<ManagedKey> managedKey = ukoService.getManagedKey(getManagedKeyOptions);
    Response<ManagedKey> managedKeyResponse = managedKey.execute();
    return managedKeyResponse.getResult();                 
}
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Update attributes of a managed key. It is only possible to modify the key's state separately from other changes. Changing a key's state affects its availablity for crypto operations in keystores.

PATCH /v4/managed_keys/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Request Body

Required*

keyUpdateRequest

Updated parameters of the key

Examples:

Example request

curl --location --request PATCH 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'If-Match: <ETag>' --data-raw '{
        "description": "updated description"
}'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

    // Initialize the uko client as specified in Authentication

  ukov4ManagedKeyOptions := ukov4.UpdateManagedKeyOptions{
    ID:          core.StringPtr("9fbae235-f24a-4a1e-b64a-57e09073f4ba"),
    UKOVault:    core.StringPtr("0487e627-f2d0-4141-9f93-54c25abe547d"),
    IfMatch:     core.StringPtr("2022-06-02T09:14:00Z"),
    Description: core.StringPtr("update description"),
  }

  managedKey, _, _ := uko.UpdateManagedKey(&ukov4ManagedKeyOptions)
  b, _ := json.MarshalIndent(managedKey, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey updateManagedKey(String id, String vaultId, String etag) {

    // Initialize the uko client/uko service as specified in Authentication

    UpdateManagedKeyOptions updateManagedKeyOptions = 
              new UpdateManagedKeyOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .description("update description")
              .build();
    ServiceCall<ManagedKey> managedKey = ukoService.updateManagedKey(updateManagedKeyOptions);
    Response<ManagedKey> managedKeyResponse = managedKey.execute();
    return managedKeyResponse.getResult();
}  
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

You can use this endpoint to obtain a list of resources associated with this managed key in IBM Cloud; which cloud resources are protected by the key you specify.

GET /v4/managed_keys/{id}/associated_resources

Request

Path Parameters

id
Required*
string
UUID of the key

Query Parameters

limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["name"]

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/associated_resources' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  listAssociatedResourcesOptions := ukov4.ListAssociatedResourcesForManagedKeyOptions{
    Limit:  core.Int64Ptr(2),
    Offset: core.Int64Ptr(0),
  }
  listAssociatedResources, _, _ := uko.ListAssociatedResourcesForManagedKey(&listAssociatedResourcesOptions)
  b, _ := json.MarshalIndent(listAssociatedResources, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static AssociatedResourceList listAssociatedResourcesForManagedKey(String id, String vaultId) {
        // Initialize the uko client/uko service as specified in Authentication

        ListAssociatedResourcesForManagedKeyOptions listAssociatedResourcesForManagedKeyOptions =
                new ListAssociatedResourcesForManagedKeyOptions.Builder()
                .id(id)
                .build();
        ServiceCall<AssociatedResourceList> templateListServiceCall =
                ukoService.listAssociatedResourcesForManagedKey(listAssociatedResourcesForManagedKeyOptions);
        Response<AssociatedResourceList> associatedResourceListResponse = templateListServiceCall.execute();
        return associatedResourceListResponse.getResult();
    }  
Copy to clipboard

Response

Response Body

associatedResourceList

The base schema for listing associated resources.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "total_count": 3,
  "limit": 20,
  "offset": 0,
  "first": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_key/5295ad47-2ce9-43c3-b9e7-e5a9482c362b/associated_resources?limit=20"
  },
  "last": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_key/5295ad47-2ce9-43c3-b9e7-e5a9482c362b/associated_resources?limit=20&offset=0"
  },
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  },
  "associated_resources": [
    {
      "vault": {
        "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
        "name": "Test Vault Name",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "managed_key": {
        "id": "93777bca-baef-4070-b9b5-a2e6079df1b4",
        "name": "My Managed Key",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "referenced_keystore": {
        "id": "93777bca-baef-4070-b9b5-a2e6079df1b4",
        "name": "My Managed Key",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "key_id_in_keystore": "93777bca-baef-4070-b9b5-a2e6079df1b4",
      "type": "com_ibm_cloud_kms_registration",
      "com_ibm_cloud_kms_registration": {
        "prevents_key_deletion": false,
        "service_name": "cloud-object-storage",
        "service_instance_name": "Cloud Object Storage-7s",
        "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/db995d8d9cc715cd99f13b0671d978b6:57da8e3a-a86d-4e01-b840-f22d36e6f23f:bucket:keyprotecttest",
        "description": "some description"
      }
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

List all managed key versions in the instance.

GET /v4/managed_keys/{id}/versions

Request

Path Parameters

id
Required*
string
UUID of the key

Query Parameters

algorithm
string[]
The algorithm of a returned key.

Allowable values: [aes,rsa,hmac,ec,des,dilithium]
state
string[]
The state that returned keys are to be in.

Allowable values: [pre_activation,active,deactivated,destroyed,compromised,destroyed_compromised]
Default: ["pre_activation","active"]
limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["-updated_at"]
label
string
The label of the key

Possible values: Value must match regular expression ^[A-Za-z0-9._ /-]+$
activation_date
string
Return only managed keys whose activation_date matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
activation_date_min
string
Return only managed keys whose activation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'activation_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
activation_date_max
string
Return only managed keys whose activation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'activation_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date
string
Return only managed keys whose deactivation_date matches the parameter. This query parameter cannot be used in conjunction with the 'expiration_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date_min
string
Return only managed keys whose deactivation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'expiration_date_min' and 'expiration_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date_max
string
Return only managed keys whose deactivation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'expiration_date_min' and 'expiration_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date
string
Return only managed keys whose deactivation_date matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date_min
string
Return only managed keys whose deactivation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'deactivation_date_min' and 'deactivation_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date_max
string
Return only managed keys whose deactivation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'deactivation_date_min' and 'deactivation_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at
string
Return only managed keys whose created_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_min
string
Return only managed keys whose created_at is at or after the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_max
string
Return only managed keys whose created_at is at or before the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at
string
Return only managed keys whose updated_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_min
string
Return only managed keys whose updated_at is after the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_max
string
Return only managed keys whose updated_at is before the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
rotated_at_min
string
Return only managed keys whose rotated_at is after the parameter value.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
rotated_at_max
string
Return only managed keys whose rotated_at is before the parameter value.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
size
string
The size of the key
size_min
string
The minimum size of the key. This query parameter cannot be used in conjunction with the 'size' query parameter.
size_max
string
The maximum size of the key. This query parameter cannot be used in conjunction with the 'size' query parameter.
referenced_keystores[].type
string[]
Type of referenced keystore. This query parameter cannot be used in conjunction with the 'instances[].keystore.type' query parameter.

Allowable values: [aws_kms,azure_key_vault,google_kms,ibm_cloud_kms,cca]
referenced_keystores[].name
string[]
Name of referenced keystore

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
instances[].keystore.type
string[]
Type of keystore supported by one of the instances. This query parameter cannot be used in conjunction with the 'referenced_keystores[].type' query parameter.

Allowable values: [aws_kms,azure_key_vault,google_kms,ibm_cloud_kms,cca]
template.name
string
Return only managed keys whose template name begins with the string.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
Example: AWS-TEMPLATE
template.id
string[]
Return only managed keys with the given template UUID.

Possible values: length = 36, Value must match regular expression ^[-0-9a-z]+$
template.type[]
string[]
Return only managed keys with the given template type.

Allowable values: [user_defined,shadow]

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/versions' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication
  
  listManagedKeyVersionOptions := ukov4.ListManagedKeyVersionsOptions{
    Limit:  core.Int64Ptr(2),
    Offset: core.Int64Ptr(0),
  }
  listKeyVersions, _, _ := uko.ListManagedKeyVersions(&listManagedKeyVersionOptions)
  b, _ := json.MarshalIndent(listKeyVersions, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKeyList listManagedKeyVersions(String id, String vaultId) {
    // Initialize the uko client/uko service as specified in Authentication

    ListManagedKeyVersionsOptions listManagedKeyVersionsOptions =
            new ListManagedKeyVersionsOptions.Builder()
            .id(id)
            .build();

    ServiceCall<ManagedKeyList> managedKeyListVersionsServiceCall = ukoService.listManagedKeyVersions();
    Response<ManagedKeyList> managedKeyListResponse = managedKeyListVersionsServiceCall.execute();
    ManagedKeyList result = managedKeyListResponse.getResult();
    return result;
}
Copy to clipboard

Response

Response Body

managedKeyList

The base schema for listing managed keys.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.

Example responses

Status 200

{
  "total_count": 4,
  "limit": 20,
  "offset": 100,
  "first": {
    "href": "/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0'"
  },
  "last": {
    "href": "/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0"
  },
  "managed_keys": [
    {
      "id": "35f690df-064a-4758-8694-b2f011810701",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-1",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "6393e930-562c-4042-b324-45c37d3d49d9",
        "name": "AZURE-template-920",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/6393e930-562c-4042-b324-45c37d3d49d9"
      },
      "version": "1,",
      "description": "AZURE KEY",
      "label": "AZUREproduction2029",
      "state": "active",
      "size": "2048",
      "algorithm": "rsa",
      "verification_patterns": [
        {
          "method": "PUB-HASH-SHA-1",
          "value\"": "947AA69D48EEE487048AF2999DADB8DA55769529"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "AZURE"
        },
        {
          "name": "ENV",
          "value": "production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AZURE-TAG"
        }
      ],
      "created_at": "2023-06-05T11:33:54.000Z",
      "updated_at": "2023-06-05T11:33:54.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "keystore": [
            {
              "id": "2e124fa5-9ef6-406c-bb2f-9ad049ff1073",
              "name": "Azure Keystore",
              "type": "azure_key_vault",
              "href": "v4/managed_keys/3dab42dc-6941-4841-8d27-4dabcc5aa09e"
            }
          ]
        }
      ],
      "instances": [
        {
          "id": "acb332dd-216c-44dd-8593-02bd2119ec62",
          "label_in_keystore\"": "AZUREproduction2029",
          "keystore": {
            "group": "Production AZURE GB",
            "type": "azure_key_vault"
          },
          "azure_key_protection_level": "software"
        }
      ],
      "href": "/v4/managed_keys/35f690df-064a-4758-8694-b2f011810701",
      "status_in_keystores": [
        {
          "keystore": [
            {
              "id": "2e124fa5-9ef6-406c-bb2f-9ad049ff1073",
              "name": "Azure Keystore",
              "type": "azure_key_vault",
              "href": "v4/managed_keys/3dab42dc-6941-4841-8d27-4dabcc5aa09e"
            }
          ],
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "d1e2525c-62c8-4df2-9173-69e1a7bc8cdb/d1e2525c-62c8-4df2-9173-69e1a7bc8cdb"
        }
      ]
    },
    {
      "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "EXAMPLE-VAULT",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
        "name": "AWS-EXAMPLE-TEMPLATE",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
      },
      "version": 1,
      "description": "AWS key template description",
      "label": "AWS-production-2029",
      "state": "active",
      "size": 256,
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method\"": "ENC-ZERO",
          "value": "C05CA1"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "AWS"
        },
        {
          "name": "ENV",
          "value": "production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AWS-TAG"
        }
      ],
      "created_at": "2023-06-05T10:40:13.000Z",
      "updated_at": "2023-06-05T10:40:19.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "0743ae15-c594-476d-8e9a-1564740ace53",
          "name": "AWS KMS Keystore 335",
          "type": "aws_kms",
          "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
        }
      ],
      "instances": [
        {
          "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
          "label_in_keystore": "AWS-production-2029",
          "type": "secret_key",
          "keystore": {
            "group\"": "Production-AWS-DE",
            "type\"": "aws_kms"
          }
        }
      ],
      "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "0743ae15-c594-476d-8e9a-1564740ace53",
            "name": "AWS KMS Keystore 335",
            "type": "aws_kms",
            "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
        }
      ]
    },
    {
      "id": "0beedc06-4608-48ae-8ae3-8b7bf3c2c39f",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-2",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "64f98479-392d-4af2-a076-77cc21b8c6f3",
        "name": "IBM-CLOUD-TEMPLATE",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/64f98479-392d-4af2-a076-77cc21b8c6f3"
      },
      "version": 1,
      "description": "",
      "label": "IBMCloudProduction2029",
      "state": "active",
      "size": "256",
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method": "ENC-ZERO",
          "value": "4ADDCB"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "IBMCloud"
        },
        {
          "name": "ENV",
          "value": "Production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AWS-TAG"
        }
      ],
      "created_at": "2023-06-05T11:59:47.000Z",
      "updated_at": "2023-06-05T11:59:47.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "0743ae15-c594-476d-8e9a-1564740ace53",
          "name": "IBM CLOUD KEYSTORE",
          "type": "ibm_cloud_kms",
          "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
        }
      ],
      "instances": [
        {
          "id": "0c5b14ea-a3dd-407c-af7c-fd74575ccbad",
          "label_in_keystore": "IBMCloudProduction2029",
          "type": "secret_key",
          "keystore": {
            "group": "Production External GB",
            "type": "ibm_cloud_kms"
          }
        }
      ],
      "href": "/v4/managed_keys/0beedc06-4608-48ae-8ae3-8b7bf3c2c39f",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "0743ae15-c594-476d-8e9a-1564740ace53",
            "name": "IBM CLOUD KEYSTORE",
            "type": "ibm_cloud_kms",
            "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "804854d0-4eb7-416e-8ae2-45ba56921c8a/804854d0-4eb7-416e-8ae2-45ba56921c8a"
        }
      ]
    },
    {
      "id": "d7b8204c-4f8f-4ba1-b306-5434ae817f51",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-3",
        "href": "v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "09d229e5-e330-4e85-a7ee-cc8555d38603",
        "name": "GOOGLE-TEMPLATE-86",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/09d229e5-e330-4e85-a7ee-cc8555d38603"
      },
      "version": 1,
      "description": "Google Key",
      "label": "Google-Production-2029",
      "state": "active",
      "size": "256",
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method\"": "ENC-ZERO",
          "value": "C3F432"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "Google"
        },
        {
          "name": "ENV",
          "value": "Production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "Google-TAG"
        }
      ],
      "created_at": "2023-06-05T13:18:28.000Z",
      "updated_at": "2023-06-05T13:18:28.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "6e026faa-d44d-4a1a-aeea-0e1ef2840cba",
          "name": "Google Keystore",
          "type": "google_kms",
          "href": "/v4/keystores/6e026faa-d44d-4a1a-aeea-0e1ef2840cba"
        }
      ],
      "instances": [
        {
          "id": "ed74a984-2057-484c-9198-54839f3fec62",
          "label_in_keystore": "Google-Production-2029",
          "type": "secret_key",
          "keystore": {
            "group": "Production Google",
            "type": "google_kms"
          },
          "google_key_protection_level": "software",
          "google_key_purpose": "encrypt_decrypt",
          "google_kms_algorithm": "google_symmetric_encryption"
        }
      ],
      "href": "/v4/managed_keys/d7b8204c-4f8f-4ba1-b306-5434ae817f51",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "6e026faa-d44d-4a1a-aeea-0e1ef2840cba",
            "name": "Google Keystore",
            "type": "google_kms",
            "href": "/v4/keystores/6e026faa-d44d-4a1a-aeea-0e1ef2840cba"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "projects/plated-field-364019/locations/europe-west3/keyRings/uko-ring/cryptoKeys/ROBOT-Google-Key-05-06-nciYX/cryptoKeyVersions/1"
        }
      ]
    }
  ],
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  }
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Return distribution status for all keystores for a key instance. If there's any problems reading the keystore status of the key instance, http code 200 will still be returned, and the error code will be returned alongside an 'error' keystore status.

GET /v4/managed_keys/{id}/status_in_keystores

Request

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/status_in_keystores' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4ManagedKeyOptions := ukov4.GetKeyDistributionStatusForKeystoresOptions{
    ID:       core.StringPtr("9fbae235-f24a-4a1e-b64a-57e09073f4ba")
  }

  managedKey, _, _ := uko.GetKeyDistributionStatusForKeystores(&ukov4ManagedKeyOptions)
  b, _ := json.MarshalIndent(managedKey, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static StatusInKeystores getKeyDistributionStatusForKeystores(String id, String vaultId) {

      // Initialize the uko client/uko service as specified in Authentication

      GetKeyDistributionStatusForKeystoresOptions getKeyDistributionStatusForKeystoresOptions =
              new GetKeyDistributionStatusForKeystoresOptions.Builder()
              .id(id)
              .build();
      ServiceCall<StatusInKeystores> keyDistributionStatusForKeystores =
              ukoService.getKeyDistributionStatusForKeystores(getKeyDistributionStatusForKeystoresOptions);
      Response<StatusInKeystores> statusInKeystoresResponse = keyDistributionStatusForKeystores.execute();
      return statusInKeystoresResponse.getResult();
  }
Copy to clipboard

Response

Response Body

statusInKeystores

Status of a key in keystores

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "status_in_keystores": [
    {
      "keystore": {
        "id": "b28bf13d-f49d-4b00-8b8d-457d38ad1e15",
        "name": "AWS KMS Keystore Name",
        "type": "aws_kms",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/b28bf13d-f49d-4b00-8b8d-457d38ad1e15"
      },
      "status": "not_present"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Update a managed key to match the latest version of the associated key template. It will install, activate, or deactivate the key on target keystores in the group defined by the key template.

POST /v4/managed_keys/{id}/update_from_template

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Query Parameters

dry_run
boolean
Do not create/update/delete a resource, only verify and validate if resource can be created/updated/deleted with given request successfully.

Default: false

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/update_from_template' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4ManagedKeyOptions := ukov4.UpdateManagedKeyFromTemplateOptions{
    ID:       core.StringPtr("9fbae235-f24a-4a1e-b64a-57e09073f4ba"),
    IfMatch:  core.StringPtr("2022-06-02T09:14:00Z")
  }

  _, managedKey, _ := uko.UpdateManagedKeyFromTemplate(&ukov4ManagedKeyOptions)
    b, _ := json.MarshalIndent(managedKey.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey updateManagedKeyFromTemplate(String id, String vaultId, String etag) {
    // Initialize the uko client/uko service as specified in Authentication

    UpdateManagedKeyFromTemplateOptions updateManagedKeyFromTemplateOptions =
            new UpdateManagedKeyFromTemplateOptions.Builder()
            .id(id)
            .ifMatch(etag)
            .build();
    ServiceCall<ManagedKey> managedKey =
            ukoService.updateManagedKeyFromTemplate(updateManagedKeyFromTemplateOptions);
    Response<ManagedKey> managedKeyResponse = managedKey.execute();
    return managedKeyResponse.getResult();
}                          
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Activate a managed key and perform key installation or activation operations on keystores in the keystore group associated with the managed key.

POST /v4/managed_keys/{id}/activate

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/activate' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4ManagedKeyOptions := ukov4.ActivateManagedKeyOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T14:33:29Z")
  }

  _, managedKey, _ := uko.ActivateManagedKey(&ukov4ManagedKeyOptions)
  b, _ := json.MarshalIndent(managedKey.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey activateManagedKey(String id, String vaultId, String etag) {

      // Initialize the uko client/uko service as specified in Authentication

      ActivateManagedKeyOptions activateManagedKeyOptions =
              new ActivateManagedKeyOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .build();
      ServiceCall<ManagedKey> managedKey = ukoService.activateManagedKey(activateManagedKeyOptions);
      Response<ManagedKey> managedKeyResponse = managedKey.execute();
      return managedKeyResponse.getResult();
  } 
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Deactivates a managed key and performs key deactivation operations on keystores in the keystore group associated with the managed key.

POST /v4/managed_keys/{id}/deactivate

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/deactivate' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

    // Initialize the uko client as specified in Authentication

  ukov4ManagedKeyOptions := ukov4.DeactivateManagedKeyOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T14:33:29Z")
  }

  _, managedKey, _ := uko.DeactivateManagedKey(&ukov4ManagedKeyOptions)
  b, _ := json.MarshalIndent(managedKey.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey deactivateManagedKey(String id, String vaultId, String etag) {

    // Initialize the uko client/uko service as specified in Authentication

    DeactivateManagedKeyOptions deActivateManagedKeyOptions =
            new DeactivateManagedKeyOptions.Builder()
            .id(id)
            .ifMatch(etag)
            .build();
    ServiceCall<ManagedKey> managedKey = ukoService.deactivateManagedKey(deActivateManagedKeyOptions);
    Response<ManagedKey> managedKeyResponse = managedKey.execute();
    return managedKeyResponse.getResult();
}   
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Destroy a managed key and perform key destruction operations on keystores in the keystore group associated with the managed key. This operation cannot be undone. The managed key must be in a 'deactivated' state.

POST /v4/managed_keys/{id}/destroy

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/destroy' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4ManagedKeyOptions := ukov4.DestroyManagedKeyOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T15:32:31Z")
  }

  _, managedKey, _ := uko.DestroyManagedKey(&ukov4ManagedKeyOptions)
  b, _ := json.MarshalIndent(managedKey.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey destroyManagedKey(String id, String vaultId, String etag) {

      // Initialize the uko client/uko service as specified in Authentication

      DestroyManagedKeyOptions destroyManagedKeyOptions = 
                new DestroyManagedKeyOptions.Builder()
                .id(id)
                .ifMatch(etag)
                .build();
      ServiceCall<ManagedKey> managedKey = ukoService.destroyManagedKey(destroyManagedKeyOptions);
      Response<ManagedKey> managedKeyResponse = managedKey.execute();
      return managedKeyResponse.getResult();
  }
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Perform the synchronization operation on a managed key to align the states in the associated keystores.

POST /v4/managed_keys/{id}/sync_status_in_keystores

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/sync_status_in_keystores' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4SyncManagedKeyOptions := ukov4.SyncManagedKeyOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T15:32:31Z")
  }

  _, statusInKeystores, _ := uko.SyncManagedKey(&ukov4SyncManagedKeyOptions)
  b, _ := json.MarshalIndent(statusInKeystores.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static StatusInKeystores syncManagedKey(String id, String vaultId, String etag) {

      // Initialize the uko client/uko service as specified in Authentication

      SyncManagedKeyOptions syncManagedKeyOptions =
                new SyncManagedKeyOptions.Builder()
                .id(id)
                .ifMatch(etag)
                .build();
      ServiceCall<StatusInKeystores> statusInKeystores = ukoService.syncManagedKey(destroyManagedKeyOptions);
      Response<StatusInKeystores> statusInKeystoresResponse = statusInKeystores.execute();
      return statusInKeystoresResponse.getResult();
  }
Copy to clipboard

Response

Response Body

statusInKeystores

Status of a key in keystores

Status Code

200
OK - It's returned when all of the statuses are successful.
207
Multi-Status - It's returned when some of the statuses contain errors.
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "status_in_keystores": [
    {
      "keystore": {
        "id": "b28bf13d-f49d-4b00-8b8d-457d38ad1e15",
        "name": "AWS KMS Keystore Name",
        "type": "aws_kms",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/b28bf13d-f49d-4b00-8b8d-457d38ad1e15"
      },
      "status": "not_present"
    }
  ]
}
Copy to clipboard

Status 207

{
  "status_in_keystores": [
    {
      "keystore": {
        "id": "b28bf13d-f49d-4b00-8b8d-457d38ad1e15",
        "name": "AWS KMS Keystore Name",
        "type": "aws_kms",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/b28bf13d-f49d-4b00-8b8d-457d38ad1e15"
      },
      "status": "not_present"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Rotate the managed key

POST /v4/managed_keys/{id}/rotate

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the key

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys/<id>/rotate' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4RotateManagedKeyOptions := ukov4.RotateManagedKeyOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T15:32:31Z")
  }

  _, managedKey, _ := uko.RotateManagedKey(&ukov4RotateManagedKeyOptions)
  b, _ := json.MarshalIndent(managedKey.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static ManagedKey rotateManagedKey(String id, String vaultId, String etag) {

      // Initialize the uko client/uko service as specified in Authentication

      RotateManagedKeyOptions rotateManagedKeyOptions =
                new RotateManagedKeyOptions.Builder()
                .id(id)
                .ifMatch(etag)
                .build();
      ServiceCall<ManagedKey> managedKeyServiceCall = ukoService.rotateManagedKey(rotateManagedKeyOptions);
      Response<ManagedKey> statusInKeystoresResponse = managedKeyServiceCall.execute();
      return statusInKeystoresResponse.getResult();
  }
Copy to clipboard

Response

Response Body

managedKey

A managed key is a key that is created in and assigned to a vault. You can manage the lifecycle of a managed key and install it to multiple keystores in the same vault. You can use a managed key for encryption and decryption only when it is installed in at least one target keystore. Installing a managed key in multiple keystores in the same vault enables key redundancy. To use a managed key for encryption and decryption, install in one or more keystores within the same vault first.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.

Example responses

Status 200

{
  "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "AWS-EXAMPLE-VAULT",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "template": {
    "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
    "name": "AWS-EXAMPLE-TEMPLATE",
    "type": [
      "user_defined"
    ],
    "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
  },
  "version": 1,
  "description": "AWS key template description",
  "label": "AWS-production-2029",
  "state": "active",
  "size": 256,
  "algorithm": "aes",
  "verification_patterns": [
    {
      "method\"": "ENC-ZERO",
      "value": "C05CA1"
    }
  ],
  "activation_date": "2028-07-14T00:00:00.000Z",
  "expiration_date": "2029-09-25T00:00:00.000Z",
  "label_tags": [
    {
      "name": "APP",
      "value": "AWS"
    },
    {
      "name": "ENV",
      "value": "production"
    },
    {
      "name": "lay",
      "value": "2029"
    }
  ],
  "tags": [
    {
      "name": "TAG-1",
      "value": "AWS-TAG"
    }
  ],
  "created_at": "2023-06-05T10:40:13.000Z",
  "updated_at": "2023-06-05T10:40:19.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "referenced_keystores": [
    {
      "id": "0743ae15-c594-476d-8e9a-1564740ace53",
      "name": "AWS KMS Keystore 335",
      "type": "aws_kms",
      "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
    }
  ],
  "instances": [
    {
      "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
      "label_in_keystore": "AWS-production-2029",
      "type": "secret_key",
      "keystore": {
        "group\"": "Production-AWS-DE",
        "type\"": "aws_kms"
      }
    }
  ],
  "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
  "status_in_keystores": [
    {
      "keystore": {
        "id": "0743ae15-c594-476d-8e9a-1564740ace53",
        "name": "AWS KMS Keystore 335",
        "type": "aws_kms",
        "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
      },
      "status": "active",
      "keystore_sync_flag": "ok",
      "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
      "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

List all key templates in the instance.

GET /v4/templates

Request

Custom Headers

Accept
string
Allowable values: [application/json,application/vnd.ibm.uko.key-template-list.v4.1+json,application/vnd.ibm.uko.key-template-list.v4.1.json+zip]

Query Parameters

name
string
Return only templates whose name begin with the string.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
Example: My Example Template
naming_scheme
string
Return only templates whose naming scheme contains the string.

Possible values: 1 ≤ length ≤ 512, Value must match regular expression .+
Example: My Example Template
vault.id
string[]
The UUID of the Vault.

Possible values: length = 36, Value must match regular expression ^[-0-9a-z]+$
key.algorithm
string[]
The algorithm of a returned key template.

Allowable values: [aes,rsa,hmac,ec,des,dilithium]
key.size
string
The size of the key
key.size_min
string
The minimum size of the key. This query parameter cannot be used in conjunction with the 'key.size' query parameter.
key.size_max
string
The maximum size of the key. This query parameter cannot be used in conjunction with the 'key.size' query parameter.
keystores[].type
string[]
Type of referenced keystore.

Allowable values: [aws_kms,azure_key_vault,google_kms,ibm_cloud_kms,cca]
keystores[].group
string[]
Group of referenced keystore.

Possible values: 1 ≤ length ≤ 200, Value must match regular expression ^[A-Za-z0-9][A-Za-z0-9-_ ]+$
created_at
string
Return only managed keys whose created_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_min
string
Return only managed keys whose created_at is at or after the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_max
string
Return only managed keys whose created_at is at or before the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at
string
Return only managed keys whose updated_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_min
string
Return only managed keys whose updated_at is after the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_max
string
Return only managed keys whose updated_at is before the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
type[]
string[]
The types of returned templates.

Allowable values: [user_defined,shadow]
Default: ["user_defined"]
Examples:
[ "user_defined" ]
state
string[]
Return only template whose state contains the string.

Allowable values: [archived,unarchived]
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["-updated_at"]
limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  //This struct can be left empty
  ukov4ListKeyTemplatesOptions := ukov4.ListKeyTemplatesOptions{
    Limit:  core.Int64Ptr(2),
    Offset: core.Int64Ptr(0),
  }

  ListKeyTemplates, _, _ := uko.ListKeyTemplates(&ukov4ListKeyTemplatesOptions)

  b, _ := json.MarshalIndent(ListKeyTemplates, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static TemplateList listKeyTemplates(String id) {

    // Initialize the uko client/uko service as specified in Authentication

    ServiceCall<TemplateList> templateListServiceCall = ukoService.listKeyTemplates();
    Response<TemplateList> templateListResponse = templateListServiceCall.execute();
    return templateListResponse.getResult();
}                       
Copy to clipboard

Response

Response Body

templateList

The base schema for listing key templates.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.

Example responses

Status 200

{
  "total_count": 3,
  "limit": 20,
  "offset": 100,
  "first": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/templates?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20"
  },
  "last": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/templates?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0"
  },
  "templates": [
    {
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "VAULT 391",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "id": "91caa113-d3ba-4620-a252-1c27aa31fd4e",
      "version": "0",
      "name": "AWS-TEMPLATE-229",
      "naming_scheme": "<APP>-AES256-<ENV>-<GROUP>-<lay>",
      "type": [
        "user_defined"
      ],
      "state": "unarchived",
      "keys_count": "0",
      "key": {
        "size": "256",
        "algorithm": "aes",
        "activation_date": "P5Y1M1W2D",
        "expiration_date": "P1Y2M1W4D",
        "state": "active"
      },
      "description": "AWS KMS KEY TEMPLATE",
      "created_at": "2023-06-05T14:16:07.000Z",
      "updated_at": "2023-06-05T14:16:07.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "keystores": [
        {
          "group": "Production-AWS-DE",
          "type": "aws_kms"
        }
      ],
      "href": "v4/templates/91caa113-d3ba-4620-a252-1c27aa31fd4e"
    },
    {
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault 391",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "id": "64f98479-392d-4af2-a076-77cc21b8c6f3",
      "version": "0",
      "name": "IBM-template-371",
      "naming_scheme": "IBMCloud<APP><ENV><lay>",
      "type": [
        "user_defined"
      ],
      "state": "unarchived",
      "keys_count": "0",
      "key": {
        "size": "256",
        "algorithm": "aes",
        "activation_date": "P5Y1M1W2D",
        "expiration_date": "P1Y2M1W4D",
        "state": "active"
      },
      "description": "IBM CLOUD key template description",
      "created_at": "2023-06-05T11:59:08.000Z",
      "updated_at": "2023-06-05T11:59:08.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "keystores": [
        {
          "group": "Production External GB",
          "type": "ibm_cloud_kms"
        }
      ],
      "href": "/v4/templates/64f98479-392d-4af2-a076-77cc21b8c6f3"
    },
    {
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault 391",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "id": "6393e930-562c-4042-b324-45c37d3d49d9",
      "version": "0",
      "name": "AZURE-TEMPLATE-920",
      "naming_scheme": "<APP><ENV><lay>",
      "type": [
        "user_defined"
      ],
      "state": "unarchived",
      "keys_count": "0",
      "key": {
        "size": "2048",
        "algorithm": "rsa",
        "activation_date": "P5Y1M1W2D",
        "expiration_date": "P1Y2M1W4D",
        "state": "active"
      },
      "description": "AZURE MANAGED KEY",
      "created_at": "2023-06-05T11:33:24.000Z",
      "updated_at": "2023-06-05T11:33:24.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "keystores": [
        {
          "group": "Production AZURE GB",
          "type": "azure_key_vault",
          "azure_key_protection_level": "software"
        }
      ],
      "href": "/v4/templates/6393e930-562c-4042-b324-45c37d3d49d9"
    },
    {
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault 391",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "id": "09d229e5-e330-4e85-a7ee-cc8555d38603",
      "version": "0",
      "name": "GOOGLE-TEMPLATE-86",
      "naming_scheme": "<APP>-<ENV>-<lay>",
      "type": [
        "user_defined"
      ],
      "state": "unarchived",
      "keys_count": "0",
      "key": {
        "size": "256",
        "algorithm": "aes",
        "activation_date": "P5Y1M1W2D",
        "expiration_date": "P1Y2M1W4D",
        "state": "active"
      },
      "description": "Google Key Template",
      "created_at": "2023-06-05T13:17:01.000Z",
      "updated_at": "2023-06-05T13:17:01.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "keystores": [
        {
          "group": "Production Google",
          "type": "google_kms",
          "google_key_protection_level": "software",
          "google_key_purpose": "encrypt_decrypt",
          "google_kms_algorithm": "google_symmetric_encryption"
        }
      ],
      "href": "/v4/templates/09d229e5-e330-4e85-a7ee-cc8555d38603"
    }
  ],
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  }
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Create a new key template. Key templates are used to combine information necessary when creating a key that allow easy subsequent key creation, without needing to specify any of its details.

POST /v4/templates

Request

Request Body

Required*

templateCreationRequest

Template object to be created

Examples:

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --data-raw '{
    "name": "IBM-Cloud-Template",
    "vault": {
        "id": "5293e55e-1cf2-4239-9f54-41336c272ec8"
    },
    "description": "Example IBM Cloud key template description",
    "keystores": [{
        "group": "Production",
        "type": "ibm_cloud_kms"
    }],
    "key": {
        "size": "256",
        "algorithm": "aes",
        "activation_date": "P5Y1M1W2D",
        "expiration_date": "P1Y2M1W4D",
        "state": "active"
    }
}'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4KeyTemplateOptions := ukov4.CreateKeyTemplateOptions{
    Vault: &ukov4.VaultReferenceInCreationRequest{
      ID: core.StringPtr("ea189243-29eb-47d2-b5d2-1eb39c73b2a1"),
    },
    Key: &ukov4.KeyProperties{
      Size:           core.StringPtr("256"),
      Algorithm:      core.StringPtr("aes"),
      ActivationDate: core.StringPtr("P5Y1M1W2D"),
      ExpirationDate: core.StringPtr("P1Y2M1W4D"),
      State:          core.StringPtr("active"),
    },
    Keystores: []ukov4.KeystoresProperties{
      {
        Group: core.StringPtr("Production"),
        Type:  core.StringPtr("ibm_cloud_kms"),
      },
    },
    Name:        core.StringPtr("IBM-Cloud-Template"),
    Description: core.StringPtr("Example description."),
  }

  keyTemplate, _, _ := uko.CreateKeyTemplate(&ukov4KeyTemplateOptions)

  b, _ := json.MarshalIndent(keyTemplate, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static Template createKeyTemplate(String id, String vaultId) {

      // Initialize the uko client/uko service as specified in Authentication

      KeyProperties keyProperties = 
              new KeyProperties.Builder()
              .size("256")
              .algorithm("aes")
              .activationDate("P5Y1M1W2D")
              .expirationDate("P1Y2M1W4D")
              .state("active")
              .build();
      KeystoresProperties keystoresProperties = 
              new KeystoresProperties.Builder()
              .group("Production")
              .type("ibm_cloud_kms")
              .build();
      VaultReferenceInCreationRequest vaultReferenceInCreationRequest =
              new VaultReferenceInCreationRequest.Builder()
              .id(id)
              .build();
      CreateKeyTemplateOptions createKeyTemplateOptions =
              new CreateKeyTemplateOptions.Builder()
              .addKeystores(keystoresProperties)
              .key(keyProperties)
              .vault(vaultReferenceInCreationRequest)
              .name("Ibm-java-cloud-template")
              .description("example description")
              .build();
      ServiceCall<Template> templateListServiceCall = ukoService.createKeyTemplate(createKeyTemplateOptions);
      Response<Template> templateResponse = templateListServiceCall.execute();
      return templateResponse.getResult();
  }
Copy to clipboard

Response

Response Body

template

A template and all its properties.

Status Code

201
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.

Example responses

Status 201

{
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "VAULT 391",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "id": "91caa113-d3ba-4620-a252-1c27aa31fd4e",
  "version": "0",
  "name": "AWS-TEMPLATE-229",
  "naming_scheme": "<APP>-AES256-<ENV>-<GROUP>-<lay>",
  "type": [
    "user_defined"
  ],
  "state": "unarchived",
  "keys_count": "0",
  "key": {
    "size": "256",
    "algorithm": "aes",
    "activation_date": "P5Y1M1W2D",
    "expiration_date": "P1Y2M1W4D",
    "state": "active"
  },
  "description": "AWS KMS KEY TEMPLATE",
  "created_at": "2023-06-05T14:16:07.000Z",
  "updated_at": "2023-06-05T14:16:07.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "keystores": [
    {
      "group": "Production-AWS-DE",
      "type": "aws_kms"
    }
  ],
  "href": "v4/templates/91caa113-d3ba-4620-a252-1c27aa31fd4e"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Delete a key template from the vault. The key template must not have any managed keys associated with it for it to be eligible for deletion.

DELETE /v4/templates/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the template

Example request

curl --location --request DELETE 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4KeyTemplateOptions := ukov4.DeleteKeyTemplateOptions{
    IfMatch:  core.StringPtr("2022-06-02T14:59:13Z")
  }

  output, _ := uko.DeleteKeyTemplate(&ukov4KeyTemplateOptions)

  b, _ := json.MarshalIndent(output, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static int deleteKeyTemplate(String id, String vaultId, String etag) {

    // Initialize the uko client/uko service as specified in Authentication

    DeleteKeyTemplateOptions deleteKeyTemplateOptions = 
              new DeleteKeyTemplateOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .build();
    ServiceCall<Void> templateListServiceCall = ukoService.deleteKeyTemplate(deleteKeyTemplateOptions);
    Response<Void> response = templateListServiceCall.execute();
    return response.getStatusCode(); // status code should be 204
}
Copy to clipboard

Response

Status Code

204
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Retrieve a key template and its details by specifying the ID.

GET /v4/templates/{id}

Request

Path Parameters

id
Required*
string
UUID of the template

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4KeyTemplateOptions := ukov4.GetKeyTemplateOptions{
    ID:       core.StringPtr("b091d5cc-c0c8-4796-ab02-f40ffb0dfffa")
  }

  keyTemplate, _, _ := uko.GetKeyTemplate(&ukov4KeyTemplateOptions)

  b, _ := json.MarshalIndent(keyTemplate, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static Template getKeyTemplate(String id, String vaultId) {

    // Initialize the uko client/uko service as specified in Authentication

    GetKeyTemplateOptions getKeyTemplateOptions = 
              new GetKeyTemplateOptions.Builder()
              .id(id)
              .build();
    ServiceCall<Template> templateListServiceCall = ukoService.getKeyTemplate(getKeyTemplateOptions);
    Response<Template> templateResponse = templateListServiceCall.execute();
    return templateResponse.getResult();
}                         
Copy to clipboard

Response

Response Body

template

A template and all its properties.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "VAULT 391",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "id": "91caa113-d3ba-4620-a252-1c27aa31fd4e",
  "version": "0",
  "name": "AWS-TEMPLATE-229",
  "naming_scheme": "<APP>-AES256-<ENV>-<GROUP>-<lay>",
  "type": [
    "user_defined"
  ],
  "state": "unarchived",
  "keys_count": "0",
  "key": {
    "size": "256",
    "algorithm": "aes",
    "activation_date": "P5Y1M1W2D",
    "expiration_date": "P1Y2M1W4D",
    "state": "active"
  },
  "description": "AWS KMS KEY TEMPLATE",
  "created_at": "2023-06-05T14:16:07.000Z",
  "updated_at": "2023-06-05T14:16:07.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "keystores": [
    {
      "group": "Production-AWS-DE",
      "type": "aws_kms"
    }
  ],
  "href": "v4/templates/91caa113-d3ba-4620-a252-1c27aa31fd4e"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Update attributes of a key template.

PATCH /v4/templates/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the template

Request Body

Required*

templateUpdateRequest

A set of properties that can be updated on template

Examples:

Example request

curl --location --request PATCH 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'If-Match: <ETag>' --data-raw '{
    "description": "updated description"
}'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4KeyTemplateOptions := ukov4.UpdateKeyTemplateOptions{
    UKOVault:    core.StringPtr("ea189243-29eb-47d2-b5d2-1eb39c73b2a1"),
    ID:          core.StringPtr("b091d5cc-c0c8-4796-ab02-f40ffb0dfffa"),
    IfMatch:     core.StringPtr("2022-06-02T14:25:28Z"),
    Description: core.StringPtr("Updated description."),
  }

  keyTemplate, _, _ := uko.UpdateKeyTemplate(&ukov4KeyTemplateOptions)

  b, _ := json.MarshalIndent(keyTemplate, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static Template updateKeyTemplate(String id, String vaultId, String etag) {

    // Initialize the uko client/uko service as specified in Authentication

    UpdateKeyTemplateOptions updateKeyTemplateOptions = 
              new UpdateKeyTemplateOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .description("Updated description.")
              .build();
    ServiceCall<Template> templateListServiceCall = ukoService.updateKeyTemplate(updateKeyTemplateOptions);
    Response<Template> templateResponse = templateListServiceCall.execute();
    return templateResponse.getResult();
}
Copy to clipboard

Response

Response Body

template

A template and all its properties.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "VAULT 391",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "id": "91caa113-d3ba-4620-a252-1c27aa31fd4e",
  "version": "0",
  "name": "AWS-TEMPLATE-229",
  "naming_scheme": "<APP>-AES256-<ENV>-<GROUP>-<lay>",
  "type": [
    "user_defined"
  ],
  "state": "unarchived",
  "keys_count": "0",
  "key": {
    "size": "256",
    "algorithm": "aes",
    "activation_date": "P5Y1M1W2D",
    "expiration_date": "P1Y2M1W4D",
    "state": "active"
  },
  "description": "AWS KMS KEY TEMPLATE",
  "created_at": "2023-06-05T14:16:07.000Z",
  "updated_at": "2023-06-05T14:16:07.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "keystores": [
    {
      "group": "Production-AWS-DE",
      "type": "aws_kms"
    }
  ],
  "href": "v4/templates/91caa113-d3ba-4620-a252-1c27aa31fd4e"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

List all target keystores in the instance.

GET /v4/keystores

Request

Custom Headers

Accept
string
Allowable values: [application/json,application/vnd.ibm.uko.keystore-list.v4.1+json,application/vnd.ibm.uko.keystore-list.v4.1.json+zip]

Query Parameters

type
string[]
Keystore type

Allowable values: [aws_kms,azure_key_vault,google_kms,ibm_cloud_kms,cca]
name
string
Return only keystores whose name contains the string.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
Example: Main IBM Cloud
description
string
Return only keystores whose description contains the string.

Possible values: 1 ≤ length ≤ 200, Value must match regular expression .+
Example: My Example Keystore Description
group
string
A Keystore group. This query parameter cannot be used in conjunction with the 'groups[]' query parameter.
groups[]
string
Keystore groups
vault.id
string[]
The UUID of the Vault.

Possible values: length = 36, Value must match regular expression ^[-0-9a-z]+$
location
string
Keystore location
limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["-updated_at"]

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4ListKeystoresOptions := ukov4.ListKeystoresOptions{
    Limit:  core.Int64Ptr(2),
    Offset: core.Int64Ptr(0),
  }

  keystores, _, _ := uko.ListKeystores(&ukov4ListKeystoresOptions)
  b, _ := json.MarshalIndent(keystores, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static KeystoreList listKeystores() {

      // Initialize the uko client/uko service as specified in Authentication

      ServiceCall<KeystoreList> templateListServiceCall = ukoService.listKeystores();
      Response<KeystoreList> keystoreListResponse = templateListServiceCall.execute();
      return keystoreListResponse.getResult();
  }                     
Copy to clipboard

Response

Response Body

keystoreList

The base schema for listing target keystores.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.

Example responses

Status 200

{
  "total_count": 3,
  "limit": 20,
  "offset": 100,
  "first": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores?limit=20"
  },
  "last": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores?limit=20&offset=0"
  },
  "keystores": [
    {
      "vault": {
        "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
        "name": "Test Vault Name",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "id": "5312861e-5b9b-4f40-9264-997afc2cd034",
      "name": "AWS KMS Keystore Name",
      "description": "AWS KMS keystore",
      "groups": [
        "Production-UK",
        "Production-DE"
      ],
      "type": "aws_kms",
      "created_at": "2022-03-09T10:59:44.000Z",
      "updated_at": "2022-03-09T10:59:44.000Z",
      "created_by": "IBMid-1308197YB4",
      "updated_by": "IBMid-1308197YB4",
      "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/5312861e-5b9b-4f40-9264-997afc2cd034",
      "aws_region": "eu-central-1",
      "aws_access_key_id": "",
      "aws_secret_access_key": ""
    },
    {
      "vault": {
        "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
        "name": "Test Vault Name",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "id": "314d0c9c-8808-47f0-829a-e63bdbb93854",
      "name": "Azure Keystore Name ",
      "description": "The AZURE keystore for testing.",
      "groups": [
        "Azure Keystore Name "
      ],
      "type": "azure_key_vault",
      "created_at": "2022-03-09T11:00:04.000Z",
      "updated_at": "2022-03-09T11:00:04.000Z",
      "created_by": "IBMid-1308197YB4",
      "updated_by": "IBMid-1308197YB4",
      "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/314d0c9c-8808-47f0-829a-e63bdbb93854",
      "azure_resource_group": "EKMF-Web-Tests",
      "azure_location": "europe_north",
      "azure_service_principal_client_id": "c8e8540f-4f15-4b6b-8862-3ccdb389e35d",
      "azure_service_principal_password": "***",
      "azure_tenant": "fcf67057-50c9-4ad4-98f3-ffca64add9e9",
      "azure_subscription_id": "a9867d9b-582f-42f3-9392-26856b06b808",
      "azure_environment": "azure"
    },
    {
      "vault": {
        "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
        "name": "Test Vault Name",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "id": "f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
      "name": "IBM Keystore Name",
      "description": "The description of the created keystore.",
      "groups": [
        "IBM Keystore Name"
      ],
      "type": "ibm_cloud_kms",
      "created_at": "2022-03-09T11:00:11.000Z",
      "updated_at": "2022-03-09T11:00:11.000Z",
      "created_by": "IBMid-1308197YB4",
      "updated_by": "IBMid-1308197YB4",
      "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
      "ibm_api_endpoint": "https://us-south.kms.cloud.ibm.com",
      "ibm_iam_endpoint": "https://iam.bluemix.net/identity/token",
      "ibm_api_key": "",
      "ibm_instance_id": "d139ea58-a073-441b-ba4e-dcc8bae58be4",
      "ibm_variant": "hpcs",
      "ibm_key_ring": "IBM-Cloud-KMS-Internal"
    }
  ],
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  }
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Create a new internal keystore or a connection to an external keystore of the requested type. If the dry_run query parameter is used, then a new keystore is not created in the database, only a test is performed to verify if the connection information is correct. It is possible to sort by the following parameters: name, created_at, updated_at, vault.id.

POST /v4/keystores

Request

Query Parameters

dry_run
boolean
Do not create/update/delete a resource, only verify and validate if resource can be created/updated/deleted with given request successfully.

Default: false

Request Body

Required*

Keystore properties to update

Examples:

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --data-raw '{
        "name": "AWS KMS Keystore Name",
        "description": "AWS KMS keystore",
        "aws_access_key_id": "JDRUDLOFEGOIGPKJBKAX",
        "aws_secret_access_key": "X3nKz4KNBFPC7RcyTR3f86XbNQEZdYPQbODlCXOF",
        "aws_region": "eu-central-1",
        "type": "aws_kms",
        "vault": {
            "id": "5293e55e-1cf2-4239-9f54-41336c272ec8"
        },
        "groups": [
            "Production-UK",
            "Production-DE"
        ]
}'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4KeystoreCreation := ukov4.KeystoreCreationRequestKeystoreTypeAwsKmsCreate{
    Type: core.StringPtr("aws_kms"),
    Vault: &ukov4.VaultReferenceInCreationRequest{
      ID: core.StringPtr("<vault_id>"),
    },
    Name:               core.StringPtr("AWS KMS Keystore Name"),
    AwsRegion:          core.StringPtr("eu-central-1"),
    AwsAccessKeyID:     core.StringPtr("<aws_accesskey_Id>"),
    AwsSecretAccessKey: core.StringPtr("<aws_secret_accesskey>"),
  }

  ukov4KeystoreOptions := ukov4.CreateKeystoreOptions{
    UKOVault:     core.StringPtr("ed6386c5-9d50-4c96-9813-d10291f6e359"),
    KeystoreBody: &ukov4KeystoreCreation,
  }

  _, keystore, _ := uko.CreateKeystore(&ukov4KeystoreOptions)
  b, _ := json.MarshalIndent(keystore.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static Keystore createKeystore(String id, String vaultId) {

    // Initialize the uko client/uko service as specified in Authentication

    VaultReferenceInCreationRequest vaultReferenceInCreationRequest =
            new VaultReferenceInCreationRequest.Builder()
            .id(id)
            .build();
    KeystoreCreationRequest keystoreCreationRequest =
            new KeystoreCreationRequestKeystoreTypeAwsKmsCreate.Builder()
            .type("aws_kms")
            .name("AWS KMS keystore name")
            .awsRegion("eu-central-1")
            .awsAccessKeyId("<AWS_ACCESSKEY>")
            .awsSecretAccessKey("<AWS_SECRET_ACCESS_KEY>")
            .vault(vaultReferenceInCreationRequest)
            .build();
    CreateKeystoreOptions createKeystoreOptions =
            new CreateKeystoreOptions.Builder()
            .keystoreBody(keystoreCreationRequest)
            .build();
    ServiceCall<Keystore> templateListServiceCall = ukoService.createKeystore(createKeystoreOptions);
    Response<Keystore> keystoreResponse = templateListServiceCall.execute();
    return keystoreResponse.getResult();
}                   
Copy to clipboard

Response

Response Body

One of

Change Schema Parameter List

A target keystore is keystore that is assigned to a vault. If it is an internal keystore, it can be created only in a vault. If it is an external keystore, you need to assign the external keystore to a vault when you connect your service instance to it.

Status Code

201
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
424
Unable to establish connection to keystore with given properties

Example responses

Status 201

{
  "vault": {
    "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "name": "Test Vault Name",
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
  },
  "id": "f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
  "name": "IBM Keystore Name",
  "description": "The description of the created keystore.",
  "groups": [
    "IBM Keystore Name"
  ],
  "type": "ibm_cloud_kms",
  "created_at": "2022-03-09T11:00:11.000Z",
  "updated_at": "2022-03-09T11:00:11.000Z",
  "created_by": "IBMid-1308197YB4",
  "updated_by": "IBMid-1308197YB4",
  "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
  "ibm_api_endpoint": "https://us-south.kms.cloud.ibm.com",
  "ibm_iam_endpoint": "https://iam.bluemix.net/identity/token",
  "ibm_api_key": "",
  "ibm_instance_id": "d139ea58-a073-441b-ba4e-dcc8bae58be4",
  "ibm_variant": "hpcs",
  "ibm_key_ring": "IBM-Cloud-KMS-Internal"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 424

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Delete an internal keystore or a connection to an external keystore (in that case, the keystore on the remote system is unchanged).

DELETE /v4/keystores/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the keystore

Query Parameters

Example request

curl --location --request DELETE 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  apikey := "FVhbNWJQFB7oEw-x-1qnDjLL6fmtZXV3z-oHe_Xa0G4D"

  token, err := ukov4.GetToken(apikey)

  if err != nil {
    fmt.Println("Error fetching the token")
    return
  }

  authenticator, err := core.NewBearerTokenAuthenticator(token)

  if err != nil {
    fmt.Println("Error assigning the token to authenticator")
    return
  }

  options := ukov4.UkoV4Options{
    Authenticator: authenticator,
    // default to the contextual url, it may be overridden by an environment variable
    URL: "https://uko.svt.us-south.hs-crypto.test.cloud.ibm.com:9573",
  }

  uko, err := ukov4.NewUkoV4UsingExternalConfig(&options)

  if err != nil {
    fmt.Println("Error creating UkoV4 client")
    return
  }

  ukov4KeystoreOptions := ukov4.DeleteKeystoreOptions{
    ID:       core.StringPtr(""),
    IfMatch:  core.StringPtr("")
  }

  keystore, _ := uko.DeleteKeystore(&ukov4KeystoreOptions)
  fmt.Println(keystore.StatusCode)
}
Copy to clipboard

Example request

public static int deleteKeystore(String id, String vaultId, String etag) {

        // Initialize the uko client/uko service as specified in Authentication

        DeleteKeystoreOptions deleteKeystoreOptions = 
                new DeleteKeystoreOptions.Builder()
                .id(id)
                .ifMatch(etag)
                .build();
        ServiceCall<Void> templateListServiceCall = ukoService.deleteKeystore(deleteKeystoreOptions);
        Response<Void> response = templateListServiceCall.execute();
        return response.getStatusCode();
    }                    
      
Copy to clipboard

Response

Status Code

204
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Retrieve a target keystore (either an internal keystore or a keystore connection) and its details by specifying the ID.

GET /v4/keystores/{id}

Request

Path Parameters

id
Required*
string
UUID of the keystore

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  apikey := "FVhbNWJQFB7oEw-x-1qnDjLL6fmtZXV3z-oHe_Xa0G4D"

  token, err := ukov4.GetToken(apikey)

  if err != nil {
    fmt.Println("Error fetching the token")
    return
  }

  authenticator, err := core.NewBearerTokenAuthenticator(token)

  if err != nil {
    fmt.Println("Error assigning the token to authenticator")
    return
  }

  options := ukov4.UkoV4Options{
    Authenticator: authenticator,
    // default to the contextual url, it may be overridden by an environment variable
    URL: "https://uko.svt.us-south.hs-crypto.test.cloud.ibm.com:9573",
  }

  uko, err := ukov4.NewUkoV4UsingExternalConfig(&options)

  if err != nil {
    fmt.Println("Error creating UkoV4 client")
    return
  }

  ukov4KeystoreOptions := ukov4.GetKeystoreOptions{
    ID:       core.StringPtr("a585b155-672d-46cc-8d50-1dfcf8a39d9d")
  }

  keystore, _, _ := uko.GetKeystore(&ukov4KeystoreOptions)
  b, _ := json.MarshalIndent(keystore, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static Keystore getKeystore(String id, String vaultId) {

    // Initialize the uko client/uko service as specified in Authentication

    GetKeystoreOptions getKeystoreOptions = 
            new GetKeystoreOptions.Builder()
            .id(id)
            .build();
    ServiceCall<Keystore> templateListServiceCall = ukoService.getKeystore(getKeystoreOptions);
    Response<Keystore> keystoreResponse = templateListServiceCall.execute();
    return keystoreResponse.getResult();
}                      
Copy to clipboard

Response

Response Body

One of

Change Schema Parameter List

A target keystore is keystore that is assigned to a vault. If it is an internal keystore, it can be created only in a vault. If it is an external keystore, you need to assign the external keystore to a vault when you connect your service instance to it.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "vault": {
    "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "name": "Test Vault Name",
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
  },
  "id": "f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
  "name": "IBM Keystore Name",
  "description": "The description of the created keystore.",
  "groups": [
    "IBM Keystore Name"
  ],
  "type": "ibm_cloud_kms",
  "created_at": "2022-03-09T11:00:11.000Z",
  "updated_at": "2022-03-09T11:00:11.000Z",
  "created_by": "IBMid-1308197YB4",
  "updated_by": "IBMid-1308197YB4",
  "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
  "ibm_api_endpoint": "https://us-south.kms.cloud.ibm.com",
  "ibm_iam_endpoint": "https://iam.bluemix.net/identity/token",
  "ibm_api_key": "",
  "ibm_instance_id": "d139ea58-a073-441b-ba4e-dcc8bae58be4",
  "ibm_variant": "hpcs",
  "ibm_key_ring": "IBM-Cloud-KMS-Internal"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Updates attributes of an internal keystore or a keystore connection.

PATCH /v4/keystores/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the keystore

Request Body

Required*

One of

Change Schema Parameter List

Keystore properties to update

Example request

curl --location --request PATCH 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'If-Match: <ETag>' --data-raw '{
        "keystore_type": "aws_kms",
        "description": "Updated description"
}'
Copy to clipboard

Example request

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4KeystoreOptions := ukov4.UpdateKeystoreOptions{
    ID:       core.StringPtr("39fdb209-3e05-4ad2-a5e7-c9339044ad57"),
    IfMatch:  core.StringPtr("2022-06-03T10:48:21Z"),
    KeystoreBody: &ukov4.KeystoreUpdateRequest{
      Description: core.StringPtr("Updated description."),
    }
  }

  keystore, _, _ := uko.UpdateKeystore(&ukov4KeystoreOptions)

  b, _ := json.MarshalIndent(keystore, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static Keystore updateKeystore(String id, String vaultId, String etag) {

    // Initialize the uko client/uko service as specified in Authentication

    KeystoreUpdateRequest keystoreUpdateRequest =
            new KeystoreUpdateRequestKeystoreTypeAwsKmsUpdate.Builder()
            .name("AWS KMS keystore name")
            .awsRegion("eu-central-1")
            .awsAccessKeyId("<AWS_ACCESKEY>")
            .awsSecretAccessKey("<AWS_ACCESS_SECRETKEY>")
            .description("update description")
            .build();
    UpdateKeystoreOptions updateKeystoreOptions = 
            new UpdateKeystoreOptions.Builder()
            .id(id)
            .ifMatch(etag)
            .keystoreBody(keystoreUpdateRequest)
            .build();
    ServiceCall<Keystore> templateListServiceCall = ukoService.updateKeystore(updateKeystoreOptions);
    Response<Keystore> keystoreResponse = templateListServiceCall.execute();
    return keystoreResponse.getResult();
}                
Copy to clipboard

Response

Response Body

One of

Change Schema Parameter List

A target keystore is keystore that is assigned to a vault. If it is an internal keystore, it can be created only in a vault. If it is an external keystore, you need to assign the external keystore to a vault when you connect your service instance to it.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "vault": {
    "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "name": "Test Vault Name",
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
  },
  "id": "f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
  "name": "IBM Keystore Name",
  "description": "The description of the created keystore.",
  "groups": [
    "IBM Keystore Name"
  ],
  "type": "ibm_cloud_kms",
  "created_at": "2022-03-09T11:00:11.000Z",
  "updated_at": "2022-03-09T11:00:11.000Z",
  "created_by": "IBMid-1308197YB4",
  "updated_by": "IBMid-1308197YB4",
  "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/keystores/f6a5ccc1-7fc3-435e-9637-482e470ba8e8",
  "ibm_api_endpoint": "https://us-south.kms.cloud.ibm.com",
  "ibm_iam_endpoint": "https://iam.bluemix.net/identity/token",
  "ibm_api_key": "",
  "ibm_instance_id": "d139ea58-a073-441b-ba4e-dcc8bae58be4",
  "ibm_variant": "hpcs",
  "ibm_key_ring": "IBM-Cloud-KMS-Internal"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

You can use this endpoint to obtain a list of resources associated with all keys referencing this keystore.

GET /v4/keystores/{id}/associated_resources

Request

Path Parameters

id
Required*
string
UUID of the keystore

Query Parameters

limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["name"]

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores/<id>/associated_resources' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  listAssociatedResourcesOptions := ukov4.ListAssociatedResourcesForTargetKeystoreOptions{
    Limit:  core.Int64Ptr(2),
    Offset: core.Int64Ptr(0),
  }
  listAssociatedResources, _, _ := uko.ListAssociatedResourcesForTargetKeystore(&listAssociatedResourcesOptions)
  b, _ := json.MarshalIndent(listAssociatedResources, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static AssociatedResourceList getAssociatedResultList(String id, String vaultId) {
         // Initialize the uko client/uko service as specified in Authentication

 ListAssociatedResourcesForTargetKeystoreOptions listAssociatedResourcesForTargetKeystoreOptions =
         new ListAssociatedResourcesForTargetKeystoreOptions.Builder()
         .id(id)
         .build();
 ServiceCall<AssociatedResourceList> associatedResourceListServiceCall =
         ukoService.listAssociatedResourcesForTargetKeystore(listAssociatedResourcesForTargetKeystoreOptions);
 Response<AssociatedResourceList> associatedResourceListResponse = associatedResourceListServiceCall.execute();
 return associatedResourceListResponse.getResult();
 }
Copy to clipboard

Response

Response Body

associatedResourceList

The base schema for listing associated resources.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "total_count": 3,
  "limit": 20,
  "offset": 0,
  "first": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_key/5295ad47-2ce9-43c3-b9e7-e5a9482c362b/associated_resources?limit=20"
  },
  "last": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_key/5295ad47-2ce9-43c3-b9e7-e5a9482c362b/associated_resources?limit=20&offset=0"
  },
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  },
  "associated_resources": [
    {
      "vault": {
        "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
        "name": "Test Vault Name",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "managed_key": {
        "id": "93777bca-baef-4070-b9b5-a2e6079df1b4",
        "name": "My Managed Key",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "referenced_keystore": {
        "id": "93777bca-baef-4070-b9b5-a2e6079df1b4",
        "name": "My Managed Key",
        "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
      },
      "key_id_in_keystore": "93777bca-baef-4070-b9b5-a2e6079df1b4",
      "type": "com_ibm_cloud_kms_registration",
      "com_ibm_cloud_kms_registration": {
        "prevents_key_deletion": false,
        "service_name": "cloud-object-storage",
        "service_instance_name": "Cloud Object Storage-7s",
        "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/db995d8d9cc715cd99f13b0671d978b6:57da8e3a-a86d-4e01-b840-f22d36e6f23f:bucket:keyprotecttest",
        "description": "some description"
      }
    }
  ]
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Retrieve status of a single target keystore (either a keystore connection or an internal keystore)

GET /v4/keystores/{id}/status

Request

Path Parameters

id
Required*
string
UUID of the keystore

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores/<id>/status' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4KeystoreStatusOptions := ukov4.GetKeystoreStatusOptions{
    ID:       core.StringPtr("39fdb209-3e05-4ad2-a5e7-c9339044ad57")
  }

  keystoreStatus, _, _ := uko.GetKeystoreStatus(&ukov4KeystoreStatusOptions)

  b, _ := json.MarshalIndent(keystoreStatus, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static KeystoreStatus getKeystoreStatus(String id, String vaultId) {

    // Initialize the uko client/uko service as specified in Authentication

    GetKeystoreStatusOptions getKeystoreStatusOptions = 
            new GetKeystoreStatusOptions.Builder()
            .id(id)
            .build();
    ServiceCall<KeystoreStatus> templateListServiceCall = ukoService.getKeystoreStatus(getKeystoreStatusOptions);
    Response<KeystoreStatus> keystoreStatusResponse = templateListServiceCall.execute();
    return keystoreStatusResponse.getResult();
}                   
Copy to clipboard

Response

Response Body

keystoreStatus

The status of the connection to the keystore

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "last_heartbeat": "2022-01-26T00:56:01.000Z",
  "health_status": "ok",
  "message": "Ping executed successfully."
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Lists all managed keys installed on the target keystore (either a keystore connection or an internal keystore). Note that pre_activation and destroyed keys are not installed.

GET /v4/keystores/{id}/managed_keys

Request

Custom Headers

Accept
string
Allowable values: [application/json,application/vnd.ibm.uko.managed-key-list.v4.1+json,application/vnd.ibm.uko.managed-key-list.v4.1.json+zip]

Path Parameters

id
Required*
string
UUID of the keystore

Query Parameters

algorithm
string[]
The algorithm of a returned key.

Allowable values: [aes,rsa,hmac,ec,des,dilithium]
state
string[]
The state that returned keys are to be in.

Allowable values: [pre_activation,active,deactivated,destroyed,compromised,destroyed_compromised]
Default: ["pre_activation","active"]
limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["-updated_at"]
label
string
The label of the key

Possible values: Value must match regular expression ^[A-Za-z0-9._ /-]+$
activation_date
string
Return only managed keys whose activation_date matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
activation_date_min
string
Return only managed keys whose activation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'activation_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
activation_date_max
string
Return only managed keys whose activation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'activation_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date
string
Return only managed keys whose deactivation_date matches the parameter. This query parameter cannot be used in conjunction with the 'expiration_date' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date_min
string
Return only managed keys whose deactivation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'expiration_date_min' and 'expiration_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
deactivation_date_max
string
Return only managed keys whose deactivation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'expiration_date_min' and 'expiration_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date
string
Return only managed keys whose deactivation_date matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date_min
string
Return only managed keys whose deactivation_date is at or after the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'deactivation_date_min' and 'deactivation_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
expiration_date_max
string
Return only managed keys whose deactivation_date is at or before the parameter value. This query parameter cannot be used in conjunction with the 'deactivation_date', 'expiration_date', 'deactivation_date_min' and 'deactivation_date_max' query parameters.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at
string
Return only managed keys whose created_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_min
string
Return only managed keys whose created_at is at or after the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
created_at_max
string
Return only managed keys whose created_at is at or before the parameter value. This query parameter cannot be used in conjunction with the 'created_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at
string
Return only managed keys whose updated_at matches the parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_min
string
Return only managed keys whose updated_at is after the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
updated_at_max
string
Return only managed keys whose updated_at is before the parameter value. This query parameter cannot be used in conjunction with the 'updated_at' query parameter.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
rotated_at_min
string
Return only managed keys whose rotated_at is after the parameter value.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
rotated_at_max
string
Return only managed keys whose rotated_at is before the parameter value.

Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
size
string
The size of the key
size_min
string
The minimum size of the key. This query parameter cannot be used in conjunction with the 'size' query parameter.
size_max
string
The maximum size of the key. This query parameter cannot be used in conjunction with the 'size' query parameter.
template.name
string
Return only managed keys whose template name begins with the string.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
Example: AWS-TEMPLATE
template.id
string[]
Return only managed keys with the given template UUID.

Possible values: length = 36, Value must match regular expression ^[-0-9a-z]+$
template.type[]
string[]
Return only managed keys with the given template type.

Allowable values: [user_defined,shadow]

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/keystores/<id>/managed_keys' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4ListManagedKeysFromKeystoreOptions := ukov4.ListManagedKeysFromKeystoreOptions{
    ID:       core.StringPtr("39fdb209-3e05-4ad2-a5e7-c9339044ad57")
  }

  managedKeys, _, _ := uko.ListManagedKeysFromKeystore(&ukov4ListManagedKeysFromKeystoreOptions)

  b, _ := json.MarshalIndent(managedKeys, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static ManagedKeyList listManagedKeysFromKeystore(String id, String vaultId) {

    // Initialize the uko client/uko service as specified in Authentication

    ListManagedKeysFromKeystoreOptions listManagedKeysFromKeystoreOptions =
            new ListManagedKeysFromKeystoreOptions.Builder()
            .id(id)
            .build();
    ServiceCall<ManagedKeyList> templateListServiceCall =
            ukoService.listManagedKeysFromKeystore(listManagedKeysFromKeystoreOptions);
    Response<ManagedKeyList> managedKeyListResponse = templateListServiceCall.execute();
    return managedKeyListResponse.getResult();
}                     
Copy to clipboard

Response

Response Body

managedKeyList

The base schema for listing managed keys.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "total_count": 4,
  "limit": 20,
  "offset": 100,
  "first": {
    "href": "/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0'"
  },
  "last": {
    "href": "/v4/managed_keys?vault.id=5295ad47-2ce9-43c3-b9e7-e5a9482c362b&limit=20&offset=0"
  },
  "managed_keys": [
    {
      "id": "35f690df-064a-4758-8694-b2f011810701",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-1",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "6393e930-562c-4042-b324-45c37d3d49d9",
        "name": "AZURE-template-920",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/6393e930-562c-4042-b324-45c37d3d49d9"
      },
      "version": "1,",
      "description": "AZURE KEY",
      "label": "AZUREproduction2029",
      "state": "active",
      "size": "2048",
      "algorithm": "rsa",
      "verification_patterns": [
        {
          "method": "PUB-HASH-SHA-1",
          "value\"": "947AA69D48EEE487048AF2999DADB8DA55769529"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "AZURE"
        },
        {
          "name": "ENV",
          "value": "production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AZURE-TAG"
        }
      ],
      "created_at": "2023-06-05T11:33:54.000Z",
      "updated_at": "2023-06-05T11:33:54.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "keystore": [
            {
              "id": "2e124fa5-9ef6-406c-bb2f-9ad049ff1073",
              "name": "Azure Keystore",
              "type": "azure_key_vault",
              "href": "v4/managed_keys/3dab42dc-6941-4841-8d27-4dabcc5aa09e"
            }
          ]
        }
      ],
      "instances": [
        {
          "id": "acb332dd-216c-44dd-8593-02bd2119ec62",
          "label_in_keystore\"": "AZUREproduction2029",
          "keystore": {
            "group": "Production AZURE GB",
            "type": "azure_key_vault"
          },
          "azure_key_protection_level": "software"
        }
      ],
      "href": "/v4/managed_keys/35f690df-064a-4758-8694-b2f011810701",
      "status_in_keystores": [
        {
          "keystore": [
            {
              "id": "2e124fa5-9ef6-406c-bb2f-9ad049ff1073",
              "name": "Azure Keystore",
              "type": "azure_key_vault",
              "href": "v4/managed_keys/3dab42dc-6941-4841-8d27-4dabcc5aa09e"
            }
          ],
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "d1e2525c-62c8-4df2-9173-69e1a7bc8cdb/d1e2525c-62c8-4df2-9173-69e1a7bc8cdb"
        }
      ]
    },
    {
      "id": "ceb54688-827c-4e31-afa8-4c0122465a5b",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "EXAMPLE-VAULT",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "7a4e3659-083b-4d77-8562-7081eb197e90",
        "name": "AWS-EXAMPLE-TEMPLATE",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/7a4e3659-083b-4d77-8562-7081eb197e90"
      },
      "version": 1,
      "description": "AWS key template description",
      "label": "AWS-production-2029",
      "state": "active",
      "size": 256,
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method\"": "ENC-ZERO",
          "value": "C05CA1"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "AWS"
        },
        {
          "name": "ENV",
          "value": "production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AWS-TAG"
        }
      ],
      "created_at": "2023-06-05T10:40:13.000Z",
      "updated_at": "2023-06-05T10:40:19.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "0743ae15-c594-476d-8e9a-1564740ace53",
          "name": "AWS KMS Keystore 335",
          "type": "aws_kms",
          "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
        }
      ],
      "instances": [
        {
          "id": "8c2bef79-dd15-477c-93f0-0ae62264d4b6",
          "label_in_keystore": "AWS-production-2029",
          "type": "secret_key",
          "keystore": {
            "group\"": "Production-AWS-DE",
            "type\"": "aws_kms"
          }
        }
      ],
      "href": "/v4/managed_keys/ceb54688-827c-4e31-afa8-4c0122465a5b",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "0743ae15-c594-476d-8e9a-1564740ace53",
            "name": "AWS KMS Keystore 335",
            "type": "aws_kms",
            "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "arn:aws:kms:eu-central-1:584492040385:key/52eca0ad-79ca-4c16-8934-986ac5d14b73"
        }
      ]
    },
    {
      "id": "0beedc06-4608-48ae-8ae3-8b7bf3c2c39f",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-2",
        "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "64f98479-392d-4af2-a076-77cc21b8c6f3",
        "name": "IBM-CLOUD-TEMPLATE",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/64f98479-392d-4af2-a076-77cc21b8c6f3"
      },
      "version": 1,
      "description": "",
      "label": "IBMCloudProduction2029",
      "state": "active",
      "size": "256",
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method": "ENC-ZERO",
          "value": "4ADDCB"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "IBMCloud"
        },
        {
          "name": "ENV",
          "value": "Production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "AWS-TAG"
        }
      ],
      "created_at": "2023-06-05T11:59:47.000Z",
      "updated_at": "2023-06-05T11:59:47.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "0743ae15-c594-476d-8e9a-1564740ace53",
          "name": "IBM CLOUD KEYSTORE",
          "type": "ibm_cloud_kms",
          "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
        }
      ],
      "instances": [
        {
          "id": "0c5b14ea-a3dd-407c-af7c-fd74575ccbad",
          "label_in_keystore": "IBMCloudProduction2029",
          "type": "secret_key",
          "keystore": {
            "group": "Production External GB",
            "type": "ibm_cloud_kms"
          }
        }
      ],
      "href": "/v4/managed_keys/0beedc06-4608-48ae-8ae3-8b7bf3c2c39f",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "0743ae15-c594-476d-8e9a-1564740ace53",
            "name": "IBM CLOUD KEYSTORE",
            "type": "ibm_cloud_kms",
            "href": "/v4/keystores/0743ae15-c594-476d-8e9a-1564740ace53"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "804854d0-4eb7-416e-8ae2-45ba56921c8a/804854d0-4eb7-416e-8ae2-45ba56921c8a"
        }
      ]
    },
    {
      "id": "d7b8204c-4f8f-4ba1-b306-5434ae817f51",
      "vault": {
        "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
        "name": "Vault-3",
        "href": "v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
      },
      "template": {
        "id": "09d229e5-e330-4e85-a7ee-cc8555d38603",
        "name": "GOOGLE-TEMPLATE-86",
        "type": [
          "user_defined"
        ],
        "href": "/v4/templates/09d229e5-e330-4e85-a7ee-cc8555d38603"
      },
      "version": 1,
      "description": "Google Key",
      "label": "Google-Production-2029",
      "state": "active",
      "size": "256",
      "algorithm": "aes",
      "verification_patterns": [
        {
          "method\"": "ENC-ZERO",
          "value": "C3F432"
        }
      ],
      "activation_date": "2028-07-14T00:00:00.000Z",
      "expiration_date": "2029-09-25T00:00:00.000Z",
      "label_tags": [
        {
          "name": "APP",
          "value": "Google"
        },
        {
          "name": "ENV",
          "value": "Production"
        },
        {
          "name": "lay",
          "value": "2029"
        }
      ],
      "tags": [
        {
          "name": "TAG-1",
          "value": "Google-TAG"
        }
      ],
      "created_at": "2023-06-05T13:18:28.000Z",
      "updated_at": "2023-06-05T13:18:28.000Z",
      "created_by": "IBMid-665000MCAR",
      "updated_by": "IBMid-665000MCAR",
      "referenced_keystores": [
        {
          "id": "6e026faa-d44d-4a1a-aeea-0e1ef2840cba",
          "name": "Google Keystore",
          "type": "google_kms",
          "href": "/v4/keystores/6e026faa-d44d-4a1a-aeea-0e1ef2840cba"
        }
      ],
      "instances": [
        {
          "id": "ed74a984-2057-484c-9198-54839f3fec62",
          "label_in_keystore": "Google-Production-2029",
          "type": "secret_key",
          "keystore": {
            "group": "Production Google",
            "type": "google_kms"
          },
          "google_key_protection_level": "software",
          "google_key_purpose": "encrypt_decrypt",
          "google_kms_algorithm": "google_symmetric_encryption"
        }
      ],
      "href": "/v4/managed_keys/d7b8204c-4f8f-4ba1-b306-5434ae817f51",
      "status_in_keystores": [
        {
          "keystore": {
            "id": "6e026faa-d44d-4a1a-aeea-0e1ef2840cba",
            "name": "Google Keystore",
            "type": "google_kms",
            "href": "/v4/keystores/6e026faa-d44d-4a1a-aeea-0e1ef2840cba"
          },
          "status": "active",
          "keystore_sync_flag": "ok",
          "keystore_sync_flag_detail": "active_key_is_active_in_keystore",
          "key_id_in_keystore": "projects/plated-field-364019/locations/europe-west3/keyRings/uko-ring/cryptoKeys/ROBOT-Google-Key-05-06-nciYX/cryptoKeyVersions/1"
        }
      ]
    }
  ],
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  }
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

List all vaults in the instance.

GET /v4/vaults

Request

Custom Headers

Accept
string
Allowable values: [application/json,application/vnd.ibm.uko.vault-list.v4.1+json,application/vnd.ibm.uko.vault-list.v4.1.json+zip]

Query Parameters

limit
integer
The number of resources to retrieve.

Possible values: 1 ≤ value ≤ 1000
Default: 20
offset
integer
The number of resources to skip.

Possible values: value ≥ 0
Default: 0
sort
string[]
Define sorting order

Possible values: Value must match regular expression ^-?[a-z0-9_.\[\],-]+$
Default: ["-updated_at"]
name
string
Return only vaults whose name begin with the string.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression ^[A-Za-z0-9#@!$%'_-][A-Za-z0-9#@!$% '_-]*$
Example: My Example Vault
description
string
Return only vaults whose description contains the string.

Possible values: 1 ≤ length ≤ 200, Value must match regular expression .+
Example: My Example Vault Description

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/vaults' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  //This struct can be left empty
  ukov4VaultOptions := ukov4.ListVaultsOptions{
    Limit:  core.Int64Ptr(2),
    Offset: core.Int64Ptr(0),
  }

  listVaults, _, _ := uko.ListVaults(&ukov4VaultOptions)

  b, _ := json.MarshalIndent(listVaults, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static VaultList listVaults(String id) {

      // Initialize the uko client/uko service as specified in Authentication
      ServiceCall<VaultList> vaults = ukoService.listVaults();
      Response<VaultList> vaultListResponse = vaults.execute();
      return vaultListResponse.getResult();
  }                    
Copy to clipboard

Response

Response Body

vaultList

The base schema for listing vaults.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

{
  "total_count": 2,
  "limit": 20,
  "offset": 100,
  "first": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults?limit=20&limit=20&offset=0"
  },
  "last": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults?limit=20&limit=20&offset=0&offset=0"
  },
  "vaults": [
    {
      "id": "d0564770-1422-420c-945f-10803a2e24de",
      "name": "EXAMPLE_VAULT_NAME",
      "description": "API Test Vault description update.",
      "created_on": "2022-03-07T09:39:17.000Z",
      "updated_on": "2022-03-07T14:31:09.000Z",
      "created_by": "IBMid-1308197YB4",
      "updated_by": "IBMid-1308197YB4",
      "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/d0564770-1422-420c-945f-10803a2e24de"
    },
    {
      "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
      "name": "Test Vault Name",
      "description": "'Test Vault Name' description.",
      "created_at": "2022-03-09T10:57:43.000Z",
      "updated_at": "2022-03-09T10:57:43.000Z",
      "created_by": "IBMid-1308197YB4",
      "updated_by": "IBMid-1308197YB4",
      "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b"
    }
  ],
  "previous": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=80"
  },
  "next": {
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/managed_keys?offset=120"
  }
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Create a new vault in the instance with the specified name and description.

POST /v4/vaults

Request

Request Body

Required*

vaultCreationRequest

Vault object to create

Examples:

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/vaults' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --data-raw '{
            "name": "VAULT",
            "description": "This is a vault"
}'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4VaultOptions := ukov4.CreateVaultOptions{
    Name:        core.StringPtr("GO_SDK_VAULT"),
    Description: core.StringPtr("This is a vault"),
  }

  vault, _, _ := uko.CreateVault(&ukov4VaultOptions)

  b, _ := json.MarshalIndent(vault, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static Vault createVault() {

    // Initialize the uko client/uko service as specified in Authentication

    CreateVaultOptions createVaultOptions = new CreateVaultOptions.Builder().name("JAVA_SDK_VAULT").description(
            "This is a vault.").build();
    ServiceCall<Vault> vault = ukoService.createVault(createVaultOptions);
    Response<Vault> vaultResponse = vault.execute();
    return vaultResponse.getResult();
}
Copy to clipboard

Response

Response Body

vault

Vaults are secure repositories for your cryptographic keys and keystores. A managed key or keystore can only be in one vault at a time.

Status Code

201
Created
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 201

[
  {
    "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "name": "Test Vault Name",
    "description": "'Test Vault Name' description.",
    "created_at": "2022-03-09T10:57:43.000Z",
    "updated_at": "2022-03-09T10:57:43.000Z",
    "created_by": "IBMid-1308197YB4",
    "updated_by": "IBMid-1308197YB4",
    "recovery_key_label": "TEKMF.AES.RECOVERY.00001",
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "keys_count": 100,
    "key_templates_count": 10,
    "keystores_count": 0
  }
]
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Delete an existing vault from the system. A vault must be empty (that is, no managed keys or keystores remain in the vault) before the vault can be deleted.

DELETE /v4/vaults/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the vault

Example request

curl --location --request DELETE 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/vaults/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4VaultOptions := ukov4.DeleteVaultOptions{
    ID:      core.StringPtr("7d0e56f0-abad-4ced-b207-301da355296d"),
    IfMatch: core.StringPtr("2022-06-01T12:57:54Z"),
  }

  output, _ := uko.DeleteVault(&ukov4VaultOptions)

  b, _ := json.MarshalIndent(output, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static int deleteVault(String vaultId, String etag) {

    // Initialize the uko client/uko service as specified in Authentication
    DeleteVaultOptions deleteVaultOptions =
            new DeleteVaultOptions.Builder()
            .ifMatch(etag)
            .id(vaultId)
            .build();
    ServiceCall<Void> voidServiceCall = ukoService.deleteVault(deleteVaultOptions);
    Response<Void> response = voidServiceCall.execute();
    return response.getStatusCode(); //status code should be 204
}              
Copy to clipboard

Response

Status Code

204
Deletion successful
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Retrieve a vault and its details by specifying the ID.

GET /v4/vaults/{id}

Request

Path Parameters

id
Required*
string
UUID of the vault

Example request

curl --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/vaults/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4VaultOptions := ukov4.GetVaultOptions{
    ID: core.StringPtr("c4754221-056b-42bb-94e4-67004cd8e9ff"),
  }

  getVault, _, _ := uko.GetVault(&ukov4VaultOptions)

  b, _ := json.MarshalIndent(getVault, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static Vault getVault(String vaultId) {

      // Initialize the uko client/uko service as specified in Authentication
      GetVaultOptions getVaultOptions = 
              new GetVaultOptions.Builder()
              .id(vaultId)
              .build();
      ServiceCall<Vault> vault = ukoService.getVault(getVaultOptions);
      Response<Vault> vaultResponse = vault.execute();
      return vaultResponse.getResult();
  }
Copy to clipboard

Response

Response Body

vault

Vaults are secure repositories for your cryptographic keys and keystores. A managed key or keystore can only be in one vault at a time.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

[
  {
    "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "name": "Test Vault Name",
    "description": "'Test Vault Name' description.",
    "created_at": "2022-03-09T10:57:43.000Z",
    "updated_at": "2022-03-09T10:57:43.000Z",
    "created_by": "IBMid-1308197YB4",
    "updated_by": "IBMid-1308197YB4",
    "recovery_key_label": "TEKMF.AES.RECOVERY.00001",
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "keys_count": 100,
    "key_templates_count": 10,
    "keystores_count": 0
  }
]
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Updates attributes of a vault.

PATCH /v4/vaults/{id}

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the vault

Request Body

Required*

vaultUpdateRequest

Vault properties to update

Examples:

Example request

curl --location --request PATCH 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/vaults/<id>' --header 'Authorization: Bearer <IAM_token>' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'If-Match: <ETag>' --data-raw '{
            "description": "This is an updated description"
}'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "net/url"
  "strings"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {
    // Initialize the uko client as specified in Authentication

  ukov4VaultOptions := ukov4.UpdateVaultOptions{
    ID:          core.StringPtr("7d0e56f0-abad-4ced-b207-301da355296d"),
    IfMatch:     core.StringPtr("2022-06-01T12:11:16Z"),
    Description: core.StringPtr("Updated description."),
  }

  vault, _, _ := uko.UpdateVault(&ukov4VaultOptions)

  b, _ := json.MarshalIndent(vault, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

public static Vault updateVault(String vaultId, String etag) {

    // Initialize the uko client/uko service as specified in Authentication
    UpdateVaultOptions updateVaultOptions = 
            new UpdateVaultOptions.Builder()
            .id(vaultId)
            .ifMatch(etag)
            .description("Update description")
            .build();
    ServiceCall<Vault> vaultServiceCall = ukoService.updateVault(updateVaultOptions);
    Response<Vault> vaultResponse = vaultServiceCall.execute();
    return vaultResponse.getResult();
}                    
Copy to clipboard

Response

Response Body

vault

Vaults are secure repositories for your cryptographic keys and keystores. A managed key or keystore can only be in one vault at a time.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found

Example responses

Status 200

[
  {
    "id": "5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "name": "Test Vault Name",
    "description": "'Test Vault Name' description.",
    "created_at": "2022-03-09T10:57:43.000Z",
    "updated_at": "2022-03-09T10:57:43.000Z",
    "created_by": "IBMid-1308197YB4",
    "updated_by": "IBMid-1308197YB4",
    "recovery_key_label": "TEKMF.AES.RECOVERY.00001",
    "href": "https://uko.us-south.hs-crypto.cloud.ibm.com:9549/api/v4/vaults/5295ad47-2ce9-43c3-b9e7-e5a9482c362b",
    "keys_count": 100,
    "key_templates_count": 10,
    "keystores_count": 0
  }
]
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Unarchive a key template.

POST /v4/templates/{id}/unarchive

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the template

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates/<id>/unarchive' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4TemplateOptions := ukov4.UnarchiveTemplateOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T14:33:29Z")
  }

  _, template, _ := uko.UnarchiveTemplate(&ukov4TemplateOptions)
  b, _ := json.MarshalIndent(template.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static Template activateTemplate(String id, String vaultId, String etag) {

      // Initialize the uko client/uko service as specified in Authentication

      ActivateTemplateOptions activateTemplateOptions =
              new ActivateTemplateOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .build();
      ServiceCall<Template> template = ukoService.activateTemplate(activateTemplateOptions);
      Response<Template> templateResponse = template.execute();
      return templateResponse.getResult();
  } 
Copy to clipboard

Response

Response Body

template

A template and all its properties.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "VAULT 391",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "id": "91caa113-d3ba-4620-a252-1c27aa31fd4e",
  "version": "0",
  "name": "AWS-TEMPLATE-229",
  "naming_scheme": "<APP>-AES256-<ENV>-<GROUP>-<lay>",
  "type": [
    "user_defined"
  ],
  "state": "unarchived",
  "keys_count": "0",
  "key": {
    "size": "256",
    "algorithm": "aes",
    "activation_date": "P5Y1M1W2D",
    "expiration_date": "P1Y2M1W4D",
    "state": "active"
  },
  "description": "AWS KMS KEY TEMPLATE",
  "created_at": "2023-06-05T14:16:07.000Z",
  "updated_at": "2023-06-05T14:16:07.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "keystores": [
    {
      "group": "Production-AWS-DE",
      "type": "aws_kms"
    }
  ],
  "href": "v4/templates/91caa113-d3ba-4620-a252-1c27aa31fd4e"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Archive a key template.

POST /v4/templates/{id}/archive

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the template

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates/<id>/archive' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4TemplateOptions := ukov4.ArchiveTemplateOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T14:33:29Z")
  }

  _, template, _ := uko.ArchiveTemplate(&ukov4TemplateOptions)
  b, _ := json.MarshalIndent(template.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static Template activateTemplate(String id, String vaultId, String etag) {

      // Initialize the uko client/uko service as specified in Authentication

      ArchiveTemplateOptions archiveTemplateOptions =
              new ArchiveTemplateOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .build();
      ServiceCall<Template> template = ukoService.archiveTemplate(archiveTemplateOptions);
      Response<Template> templateResponse = template.execute();
      return templateResponse.getResult();
  } 
Copy to clipboard

Response

Response Body

template

A template and all its properties.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "VAULT 391",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "id": "91caa113-d3ba-4620-a252-1c27aa31fd4e",
  "version": "0",
  "name": "AWS-TEMPLATE-229",
  "naming_scheme": "<APP>-AES256-<ENV>-<GROUP>-<lay>",
  "type": [
    "user_defined"
  ],
  "state": "unarchived",
  "keys_count": "0",
  "key": {
    "size": "256",
    "algorithm": "aes",
    "activation_date": "P5Y1M1W2D",
    "expiration_date": "P1Y2M1W4D",
    "state": "active"
  },
  "description": "AWS KMS KEY TEMPLATE",
  "created_at": "2023-06-05T14:16:07.000Z",
  "updated_at": "2023-06-05T14:16:07.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "keystores": [
    {
      "group": "Production-AWS-DE",
      "type": "aws_kms"
    }
  ],
  "href": "v4/templates/91caa113-d3ba-4620-a252-1c27aa31fd4e"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Expose a key template.

POST /v4/templates/{id}/expose

Request

Custom Headers

If-Match
Required*
string
Precondition of the update; Value of the ETag from the header on a GET request.

Path Parameters

id
Required*
string
UUID of the template

Example request

curl --location --request POST 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/templates/<id>/expose' --header 'Authorization: Bearer <IAM_token>' --header 'Accept: application/json' --header 'If-Match: <ETag>'
Copy to clipboard

Example request

package main

import (
  "encoding/json"
  "fmt"

  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/ibm-hpcs-uko-sdk/ukov4"
)

func main() {

  // Initialize the uko client as specified in Authentication

  ukov4TemplateOptions := ukov4.ExposeTemplateOptions{
    ID:       core.StringPtr("24829556-bcc8-49e7-9a22-512feddbfce3"),
    IfMatch:  core.StringPtr("2022-06-02T14:33:29Z")
  }

  _, template, _ := uko.ExposeTemplate(&ukov4TemplateOptions)
  b, _ := json.MarshalIndent(template.Result, "", "  ")
  fmt.Println(string(b))

}
Copy to clipboard

Example request

public static Template activateTemplate(String id, String vaultId, String etag) {

      // Initialize the uko client/uko service as specified in Authentication

      ExposeTemplateOptions exposeTemplateOptions =
              new ExposeTemplateOptions.Builder()
              .id(id)
              .ifMatch(etag)
              .build();
      ServiceCall<Template> template = ukoService.exposeTemplate(exposeTemplateOptions);
      Response<Template> templateResponse = template.execute();
      return templateResponse.getResult();
  } 
Copy to clipboard

Response

Response Body

template

A template and all its properties.

Status Code

200
OK
400
Bad request. At least one of the parameters or headers is invalid. Details are in the response body.
401
You're unauthorized to perform this operation.
403
You don't have sufficient permissions to the specified resource(s) to perform this operation or the operation is forbidden.
404
One or more resources not found
409
The request could not be completed due to a conflict with the current state of the target resource or because a resource with the same unique identifier (key label, keystore name) already exists.
412
One or more conditions given in the request header fields were evaluated with the result 'false' when tested on the server. The underlying resource may have been modified in the meantime.
428
The server requires the request to be conditional; use the If-Match header.

Example responses

Status 200

{
  "vault": {
    "id": "1d3b402a-ce40-4b17-b6f0-a7fa26ba72de",
    "name": "VAULT 391",
    "href": "/v4/vaults/1d3b402a-ce40-4b17-b6f0-a7fa26ba72de"
  },
  "id": "91caa113-d3ba-4620-a252-1c27aa31fd4e",
  "version": "0",
  "name": "AWS-TEMPLATE-229",
  "naming_scheme": "<APP>-AES256-<ENV>-<GROUP>-<lay>",
  "type": [
    "user_defined"
  ],
  "state": "unarchived",
  "keys_count": "0",
  "key": {
    "size": "256",
    "algorithm": "aes",
    "activation_date": "P5Y1M1W2D",
    "expiration_date": "P1Y2M1W4D",
    "state": "active"
  },
  "description": "AWS KMS KEY TEMPLATE",
  "created_at": "2023-06-05T14:16:07.000Z",
  "updated_at": "2023-06-05T14:16:07.000Z",
  "created_by": "IBMid-665000MCAR",
  "updated_by": "IBMid-665000MCAR",
  "keystores": [
    {
      "group": "Production-AWS-DE",
      "type": "aws_kms"
    }
  ],
  "href": "v4/templates/91caa113-d3ba-4620-a252-1c27aa31fd4e"
}
Copy to clipboard

Status 400

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 401

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 403

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 404

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 409

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 412

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Status 428

{
  "status_code": 400,
  "trace": "9daee671-916a-4678-850b-10b9110236d",
  "error": {
    "code": "invalid_parameter_value",
    "message": "Value of the parameter 'algorithm' is invalid: 'ec'.",
    "more_info": "https://cloud.ibm.com/apidocs/uko#create-key-template",
    "target": {
      "type": "parameter",
      "name": "algorithm"
    }
  }
}
Copy to clipboard

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Metadata

Change log

Methods

List managed keys

Request

Custom Headers

Accept

Query Parameters

vault.id

algorithm

state

limit

offset

sort

label

activation_date

activation_date_min

activation_date_max

deactivation_date

deactivation_date_min

deactivation_date_max

expiration_date

expiration_date_min

expiration_date_max

created_at

created_at_min

created_at_max

updated_at

updated_at_min

updated_at_max

rotated_at_min

rotated_at_max

size

size_min

size_max

referenced_keystores[].type

referenced_keystores[].name

instances[].keystore.type

template.name

template.id

template.type[]

Response

Response Body

total_count

limit

offset

managed_keys

first

last

previous

next

Status Code

200

400

401

403

Create a managed key

Request

Request Body

template_name

vault

label

description

Response

Response Body

id

vault

template

version

description

label

state

size

algorithm

verification_patterns