IBM Cloud API Docs

Introduction

Last updated: 2024-05-16

IBM® Key Protect for IBM Cloud® helps you provision encrypted keys for apps across IBM Cloud. As you manage the lifecycle of your keys, you can benefit from knowing that your keys are secured by cloud-based FIPS 140-2 Level 3 hardware security modules (HSMs) that protect against the theft of information.

Key Protect provides a REST API that you can use with any programming language to store, retrieve, and generate encryption keys. For details about using Key Protect, see the IBM Cloud docs.

API endpoint

https://<region>.kms.cloud.ibm.com

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more information, see Regions and locations.

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

go get -u github.com/IBM/keyprotect-go-client

GitHub:

https://github.com/IBM/keyprotect-go-client

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

npm install @ibm-cloud/ibm-key-protect

GitHub:

https://github.com/IBM/keyprotect-nodejs-client

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

pip install -U keyprotect

GitHub:

https://github.com/IBM/keyprotect-python-client

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

git clone https://github.com/IBM/keyprotect-java-client
cd keyprotect-java-client
mvn install

GitHub:

https://github.com/IBM/keyprotect-java-client

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 Key Protect.

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. For example, if you created a Key Protect service instance for the us-south region, use the following endpoint and API headers to browse keys in your service:

curl -X GET \
    https://us-south.kms.cloud.ibm.com/api/v2/keys \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <access_token>" \
    -H "bluemix-instance: <instance_ID>"

Replace <access_token> with your Cloud IAM token, and <instance_ID> with the IBM Cloud instance ID that identifies your Key Protect service instance.

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

To find out more about setting up the Key Protect API, see Accessing the API.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides client config initialization method in which you will need to replace <key_protect_url> with the appropriate service endpoint, the <api_key> with the API key associated with your application, and <instance_ID> with the IBM Cloud instance ID that identifies your Key Protect service instance.

The value kp.DefaultTokenURL for TokenURL defaults to the IAM production URL, but you may need to alter the value to be associated with virtual private networks. Use the client config options in the method to create a new Key Protect client. The method handles the authentication procedure with the provided API_KEY.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to export environment variables to match the IBMCLOUD_API_KEY term with the API key associated with your service credentials, another term, IAM_AUTH_URL with the appropriate URL like 'https://iam.cloud.ibm.com/identity/token', another term, KP_SERVICE_URL with the endpoint, including the region, such as https://us-south.kms.cloud.ibm.com, and KP_INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

To retrieve your instance ID:

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

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to replace the IBMCLOUD_API_KEY with the API key associated with your application, and KP_INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to replace the IBMCLOUD_API_KEY with the API key associated with your application, and KP_INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

IBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to replace the IAM_API_KEY with the API key associated with your application, IAM_AUTH_URL with your Cloud IAM token,KEY_PROTECT_URL with a service endpoint, and INSTANCE_ID with the IBM Cloud instance ID that identifies your Key Protect service instance.

To retrieve your access token:

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

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 Key Protect service instance. The GUID value in the JSON output represents the instance ID for the service.

To authenticate to Key Protect API:

import (
    "context"
    "encoding/json"
    "fmt"

    kp "github.com/IBM/keyprotect-go-client"
)

func getConfigAPIKey() kp.ClientConfig {
    return kp.ClientConfig{
        BaseURL:    <key_protect_url>,
        APIKey:     <api_key>,
        TokenURL:   kp.DefaultTokenURL,
        InstanceID: <instance_ID>,
        Verbose:    kp.VerboseFailOnly,
    }
}

func main() {
    options := getConfigAPIKey()
    api, err := kp.New(options, kp.DefaultTransport())
    if err != nil {
        fmt.Println("Error creating kp client")
        return
    }
}

To access the API through your service endpoint, you will need to use the following format.

API endpoint format:

https://<region>.kms.cloud.ibm.com

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more informaton, see Regions and locations.

To retrieve your instance ID, run the following command using the CLI:

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

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

To authenticate to Key Protect API:

const KeyProtectV2 = require('@ibm-cloud/ibm-key-protect/ibm-key-protect-api/v2');
const { IamAuthenticator } = require('@ibm-cloud/ibm-key-protect/auth');

// using external configuration of environment variables
const envConfigs = {
    apiKey: process.env.IBMCLOUD_API_KEY,
    iamAuthUrl: process.env.IAM_AUTH_URL,
    serviceUrl: process.env.KP_SERVICE_URL,
    bluemixInstance: process.env.KP_INSTANCE_ID,
};

// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
    apikey: envConfigs.apiKey,
    url: envConfigs.iamAuthUrl,
});

// Construct the service client.
const keyProtectClient = new KeyProtectV2({
    authenticator,
    serviceUrl: envConfigs.serviceUrl,
});

For more information on the regional endpoint where your data can be accessed, see Regions and locations.

To authenticate to Key Protect API:

import os

import keyprotect
from keyprotect import bxauth

tm = bxauth.TokenManager(api_key=os.getenv("<IBMCLOUD_API_KEY>"))

kp = keyprotect.Client(
    credentials=tm,
    region="<region>",
    service_instance_id=os.getenv("<KP_INSTANCE_ID>")
)

Replace <IBMCLOUD_API_KEY> with your service credentials.

Replace <KP_INSTANCE_ID> with the UUID that identifies your Key Protect instance.

To retrieve your instance ID:

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

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more information, see Regions and locations.

To authenticate to Key Protect API:

import com.ibm.cloud.ibm_key_protect_api.v2.IbmKeyProtectApi;
import com.ibm.cloud.ibm_key_protect_api.v2.model.*;
import com.ibm.cloud.sdk.core.http.Response;
import com.ibm.cloud.sdk.core.security.*;

public class KPClient {
    
    private static IbmKeyProtectApi testClient;

    public static void main(String[] args) {
        
        IamAuthenticator authenticator = new IamAuthenticator("<IAM_API_KEY>");
        authenticator.setURL("<IAM_AUTH_URL>");
        authenticator.validate();
        
        testClient = new IbmKeyProtectApi("<INSTANCE_ID>", authenticator);
        testClient.setServiceUrl("<KEY_PROTECT_URL>");
    }
}

Replace <INSTANCE_ID> with the UUID that identifies your Key Protect instance.

Replace <IAM_API_KEY> with your service credentials.

Replace <IAM_AUTH_URL> with https://iam.cloud.ibm.com/identity/token.

Replace <KEY_PROTECT_URL> with the service endpoint for your instance that handles your requests.

To retrieve your instance ID, replace <instance_name> in the command as shown:

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

Your endpoint is specific to the geographic area where your Key Protect service instance resides. For more information, see Regions and locations.

Auditing

You can monitor API activity within your account. Whenever an API method is called, an event is generated that you can then track and audit. The specific event type is listed for each method that generates auditing events. For methods that don't list any events, no events are generated.

For more information about how to track Key Protect activity, see Auditing the events for Key Protect.

Error handling

The Key Protect service 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.

Table 1. 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; ensure no required parameters are missing.
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 Key Protect's end.

Metadata

When you create or store keys in Key Protect, 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 Key Protect key.

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

Pagination

Some API requests might return a large number of results. By specifying the limit and offset parameters at query time, you can retrieve a subset of your keys, starting with the offset value that you specify. For more information, see Retrieving a subset of keys.

There are optional operations that can effect pagination and the resulting list of keys returned by the service. Some operations may still be in development, and will be listed as "Beta" while that is the case.

Search

When used, this operation performs a search, possibly limiting the number of keys returned. If you want to narrow the number of results returned by a search, try using one or a combination of the following values as a prefix for the term you wish to have searched:

  • not: when specified, inverts the logic the search uses (for example, not:foo will search for keys that have aliases or names that do not contain foo).
  • escape: everything after this option is take as plaintext (example: escape:not: will search for keys that have an alias or name containing the substring not:).
  • exact: only looks for exact matches.
  • alias: only looks for key aliases.
  • name: only looks for key names.

The list of keys returned is sorted on id by default, if this parameter is not provided.

Sort

When used, this operation sorts the list of keys returned based on one or more key properties. The key properties that can be sorted at this time are:

  • id
  • state
  • extractable
  • imported
  • creationDate
  • lastUpdateDate
  • lastRotateDate
  • deletionDate
  • expirationDate

The list of keys returned is sorted on id by default, if this parameter is not provided.

Rate Limiting

Rate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

An HTTP status code of 429 indicates that the rate limit has been exceeded.

Change log

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

New features will be initially released as "beta" implementations.

"Beta" means that the specification is subject to change, with limited support in different environments (from partial support to none at all, depending on the specifics), in order to test new features that are not yet stable for use in production environments.

As part of continued migration and improvement, the algorithmBitSize, algorithmMode, algorithmType and algorithmMetadata fields are deprecated within the Key Protect API.

Key Protect announces several changes to both the structure and to particular names of certain events to better conform with IBM naming conventions.

The alias parameter in the event generated with a key alias added to a key at creation time is being moved from the response data section to the request data section.

Also, to better conform with IBM standards, the names of certain events are changing.

Table 2. Event name changes
Old event name New event name
kms.secrets.eventack kms.secrets-event.ack
kms.secrets.readmetadata kms.secrets-metadata.read
kms.secrets.listkeyversions kms.secrets-key-versions.list
kms.secrets.defaultalias kms.secrets-alias.default
kms.secrets.createalias kms.secrets-alias.create
kms.secrets.deletealias kms.secrets-alias.delete
kms.importtoken.create kms.import-token.create
kms.importtoken.default kms.import-token.default
kms.importtoken.read kms.import-token.read
kms.instancepolicies.write kms.instance-policies.write
kms.instancepolicies.default kms.instance-policies.default
kms.instancepolicies.read kms.instance-policies.read
kms.instance.readallowedipport kms.instance-allowed-ip-port.read
kms.instance.readipwhitelistport kms.instance-ip-whitelist-port.read
kms.keyrings.create kms.key-rings.create
kms.keyrings.delete kms.key-rings.delete
kms.keyrings.list kms.key-rings.list
kms.keyrings.default kms.key-rings.default
kms.governance.configread kms.governance-config.read

Methods

Create a key

Creates a new key with specified key material.

Key Protect designates the resource as either a root key or a standard key based on the extractable value that you specify. A successful POST /keys operation adds the key to the service and returns the details of the request in the response entity-body, if the Prefer header is set to return=representation.

POST /api/v2/keys

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • kms.secrets.create

Auditing

Calling this method generates the following auditing event.

  • kms.secrets.create

Request

Custom Headers

  • Bluemix-Instance
    Required*
    string

    The IBM Cloud instance ID that identifies your Key Protect service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

  • Correlation-Id
    string

    The v4 UUID used to correlate and track transactions.

    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

  • Prefer
    string

    Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

    Allowable values: [return=representation,return=minimal]

    Possible values: 14 ≤ length ≤ 21

  • X-Kms-Key-Ring
    string

    The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

    Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

    Default: default

Request Body

Required*
application/vnd.ibm.kms.key+jsonOne of

    The base request for creating a new key.

    Example: 
    {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "A Key Protect key",
      "extractable": false
    }
  ]
}
    • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.key+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "type": "application/vnd.ibm.kms.key+json",
        "name": "Root-key",
        "description": "A Key Protect key",
        "extractable": false
      }
    ]
  }'
    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  // Method CreateKeyWithAliases supports creating key with aliases. To provide alias names pass array of strings to the method 
  // otherwise pass nil.
  rootkey, err := api.CreateKeyWithAliases(context.Background(), <key_name>, <expiration_date>, <extractable>, <aliases>)
  if err != nil {
    fmt.Println("Error while creating key: ", err)
    return
  }
  b, _ := json.MarshalIndent(rootkey, "", "  ")
  fmt.Println(string(b))
}
    • // Initialize the Key Protect client as specified in Authentication

// Define the key parameters
const body = {
  metadata: {
    collectionType: 'application/vnd.ibm.kms.key+json',
    collectionTotal: 1,
  },
  resources: [
    {
      type: 'application/vnd.ibm.kms.key+json',
      name: 'nodejsKey',
      extractable: false,
    },
  ],
};
const createParams = Object.assign({}, envConfigs);
createParams.body = body;
const response = keyProtectClient.createKey(createParams);
const keyId = response.result.resources[0].id;
console.log('Key created, id is: ' + keyId);
    • import os

import keyprotect
from keyprotect import bxauth

# Initialize the Key Protect client as specified in Authentication
key = kp.create(name="<key_name>")
print("Created key '%s'" % key["id"])
    • // payload is null if not an imported key
// payload should be base64 encoded string
// notRootKey is false if this is a root key
public static String createKey(String keyName, String keyDescription, String payload, boolean notRootKey) {
  
  InputStream inputstream = null;
  CreateKeyOptions createKeyOptionsModel = null;
  
  try {
    // build json format input stream
    JsonObjectBuilder resourceObjectBuilder = Json.createObjectBuilder()
      .add("name", keyName)
      .add("extractable", notRootKey)
      .add("description", keyDescription);

    // imported key
    if (payload != null) {
      resourceObjectBuilder.add("payload", payload);
    }

    JsonObjectBuilder jsonObjectBuilder = Json.createObjectBuilder()
      .add("metadata", Json.createObjectBuilder()
        .add("collectionType", "application/vnd.ibm.kms.key+json")
        .add("collectionTotal", 1))
      .add("resources", Json.createArrayBuilder()
        .add(resourceObjectBuilder));

    JsonObject jsonObject = jsonObjectBuilder.build();

    inputstream = new ByteArrayInputStream(jsonObject.toString().getBytes());
  
    createKeyOptionsModel = new CreateKeyOptions.Builder()
      .bluemixInstance("<instance_id>")
      .createKeyOneOf(inputstream)
      .prefer("return=representation")
      .build();
      
  } catch(ClassCastException e) {
    System.out.println("Error: " + e.toString());
    return "failed to create key";
  }
  
  Response<Key> response = testClient.createKey(createKeyOptionsModel).execute();
  List<KeyWithPayload> key = response.getResult().getResources();  
  return key.toString();
}

    Response

    Response Body

    Key

    Properties associated with a key response.

    Status Code

    • 201

      The key was successfully created.

    • 400

      The key is missing a required field.

    • 401

      Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

    • 403

      Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

    • 404

      There are three possible causes for HTTP 404 while trying to create a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

      KEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note the default key ring name is "default."

      INSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist.

      IMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist.

    • 409

      The import token that was used to encrypt this key has reached its maxAllowedRetrievals or expirationDate, and it is no longer available for operations. To create a new import token, use POST /import_token.

      In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to 409 conflict exceptions.

      KEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached.

      KEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance.

      KEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Key Protect only permits the creation or import of keys in your Key Protect instance that follow the key creation and import settings listed on the keyCreateImportAccess policy.

      IMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.

    • 429

      Too many requests. Wait a few minutes and try again.

    • 500

      IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

    Example responses
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": false,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key is missing a required field."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: The import token that was used to encrypt this key has reached its 'maxAllowedRetrievals' or 'expirationDate', and it is no longer available for key operations. To create a new import token, use 'POST /import_token'."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

    List keys

    Retrieves a list of keys that are stored in your Key Protect service instance.

    Important: When a user of Key Protect on Satellite views lists of keys through the IBM Console, or programmatically via this API, keys with "fine grain" permissions won't appear due to the manner in which the service aggregates the collection. While the user can still use the key resource, only by using the CLI or API and passing the specific key ID can a user access the metadata and other details of the key.

    Note: GET /keys will not return the key material in the response body. You can retrieve the key material for a standard key with a subsequent GET /keys/{id} request.

    GET /api/v2/keys

    Authorization

    To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

    • kms.secrets.list

    Auditing

    Calling this method generates the following auditing event.

    • kms.secrets.list

    Request

    Custom Headers

    • Bluemix-Instance
      Required*
      string

      The IBM Cloud instance ID that identifies your Key Protect service instance.

      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

    • X-Kms-Key-Ring
      string

      The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

      Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

    Query Parameters

    • limit
      integer

      The number of keys to retrieve. By default, GET /keys returns the first 200 keys. To retrieve a different set of keys, use limit with offset to page through your available resources. The maximum value for limit is 5,000. Usage: If you have 20 keys in your instance, and you want to retrieve only the first 5 keys, use ../keys?limit=5.

      Possible values: 1 ≤ value ≤ 5000

      Default: 200

    • offset
      integer

      The number of keys to skip. By specifying offset, you retrieve a subset of keys that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have 100 keys in your instance, and you want to retrieve keys 26 through 50, use ../keys?offset=25&limit=25.

      Possible values: value ≥ 0

      Default: 0

    • state
      integer[]

      The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. Usage: If you want to retrieve active and deleted keys, use ../keys?state=1,5.

      Allowable values: [0,1,2,3,5]

      Possible values: 0 ≤ number of items ≤ 5, 0 ≤ value ≤ 5

      Default: [0,1,2,3]

    • extractable
      boolean

      The type of keys to be retrieved. Filters keys based on the extractable property. You can use this query parameter to search for keys whose material can leave the service. If set to true, standard keys will be retrieved. If set to false, root keys will be retrieved. If omitted, both root and standard keys will be retrieved. Usage: If you want to retrieve standard keys, use ../keys?extractable=true.

    • search
      string

      When provided, performs a search, possibly limiting the number of keys returned. Examples:

      • foobar - find keys where the name or any of its aliases contain foobar, case insentive (i.e. matches xfoobar, Foobar).
      • fadedbee-0000-0000-0000-1234567890ab (a valid key id) - find keys where the id the key is fadedbee-0000-0000-0000-1234567890ab, or the name or any of its aliases contain fadedbee-0000-0000-0000-1234567890ab, case insentive.

      May prepend with options:

      • not: = when specified, inverts matching logic (example: not:foo will search for keys that have aliases or names that do not contain foo)
      • escape: = everything after this option is take as plaintext (example: escape:not: will search for keys that have an alias or name containing the substring not:)
      • exact: = only looks for exact matches

      May prepend with search scopes:

      • alias: = search in key aliases for search query
      • name: = search in key names for search query

      Examples:

      • not:exact:foobar/exact:not:foobar - find keys where the name nor any of its aliases are not exactly foobar (i.e. matches xfoobar, bar, foo)
      • exact:escape:not:foobar - find keys where the name or any of its aliases are exactly not:foobar
      • not:alias:foobar/alias:not:foobar - find keys where any of its aliases do not contain foobar
      • name:exact:foobar/exact:name:foobar - find keys where the name is exactly foobar

      Note:

      By default, if no scopes are provided, search will be performed in both name and alias scopes.

      Search is only possible on a intial searchable space of at most 5000 keys. If the initial seachable space is greater than 5000 keys, the API returns HTTP 400 with the property resouces[0].reasons[0].code equals to 'KEY_SEARCH_TOO_BROAD'. Use the following filters to reduce the initial searchable space:

      • state (query parameter)
      • extractable (query parameter)
      • X-Kms-Key-Ring (HTTP header)

      If the total intial searchable space exceeds the 5000 keys limit and when providing a fully specified key id or when searching within the alias scope, a lookup will be performed and if a key is found, the key will be returned as the only resource and in the response metadata the property incompleteSearch will be true.

      When providing a fully specified key id or when searching within the alias scope, a key lookup is performed in addition to the search. This means search will try to lookup a single key that is uniquely identified by the key id or provided alias, this key will be included in the response as the first resource, before other matches.

      Search scopes are disjunctive, behaving in an OR manner. When using more than one search scope, a match in at least one of the scopes will result in the key being returned.

      Possible values: 0 ≤ length ≤ 256, Value must match regular expression ^.{0,256}$

    • sort
      string

      When provided, sorts the list of keys returned based on one or more key properties. To sort on a property in descending order, prefix the term with "-". To sort on multiple key properties, use a comma to separate each properties. The first property in the comma-separated list will be evaluated before the next. The key properties that can be sorted at this time are:

      • id
      • state
      • extractable
      • imported
      • creationDate
      • lastUpdateDate
      • lastRotateDate
      • deletionDate
      • expirationDate

      The list of keys returned is sorted on id by default, if this parameter is not provided.

      Allowable values: [id,state,extractable,imported,creationDate,lastUpdateDate,lastRotateDate,deletionDate,expirationDate]

      Possible values: 2 ≤ length ≤ 14

      Default: id

    • filter
      string

      When provided, returns the list of keys that match the queried properties. Each key property to be filtered on is specified as the property name itself, followed by an “=“ symbol, and then the value to filter on, followed by a space if there are more properties to filter only. Note: Anything between < and > in the examples or descriptions represent placeholder to specify the value Basic format: = = - The value to filter on may contain a value related to the property itself, or an operator followed by a value accepted by the operator - Only one operator and value, or one value is accepted per property at a time Format with operator/value pair: =: Up to three of the same property may be specified at a time. The key properties that can be filtered at this time are:

      • creationDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • deletionDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • expirationDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • extractable
        • Boolean true or false without quotes, case-insensitive
      • lastRotateDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • lastUpdateDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • state
        • A list of comma-separated integers with no space in between: 0,1,2,3,5 Comparison operations (operators) that can be performed on date values are:
      • lte:<value> Less than or equal to - lt:<value> Less than - gte:<value> Greater than or equal to - gt:<value> Greater than A special keyword for date, none (case-insensitive), may be used to retreive keys that do not have that property. This is useful for lastRotateDate, where only keys that have never been rotated can be retreived. Examples:
      • lastRotateDate="2022-02-15T00:00:00Z" Filter keys that were last rotated on February 15, 2022 - lastRotateDate=gte:"2022-02-15T00:00:00Z" Filter keys that were last rotated after or on February 15, 2022 - lastRotateDate=gte:"2022-02-15T00:00:00Z" lastRotateDate=lt:"2022-03-15T00:00:00Z" Filter keys that were last rotated after or on February 15, 2022 but before (not including) March 15, 2022 - lastRotateDate="2022-02-15T00:00:00Z" state=0,1,2,3,5 extractable=false Filter root keys that were last rotated on February 15, 2022, with any state Note: When you filter by state or extractable in this query parameter, you will not be able to use the deprecated state or extractable independent query parameter. You will get a 400 response code if you specify a value for one of the two properties in both this filter query parameter and the deprecated independent query of the same name (the same applies vice versa).

      Possible values: 0 ≤ length ≤ 512, Value must match regular expression ^.{0,512}$

    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys   -H 'accept: application/vnd.ibm.kms.key+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  keys, err := api.GetKeys(context.Background(), <limit>, <offset>)
  if err != nil {
    fmt.Println("Error while retrieving keys: ", err)
    return
  }
  b, _ := json.MarshalIndent(keys, "", "  ")
  fmt.Println(string(b))
}
    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  limit := uint32(5)
  offset := uint32(0)
  extractable := false
  keyStates := []kp.KeyState{kp.KeyState(kp.Active), kp.KeyState(kp.Suspended)}


  listKeysOptions := &kp.ListKeysOptions{
    Limit : &limit,
    Offset : &offset,
    Extractable : &extractable,
    State : keyStates,
  }

  keys, err := client.ListKeys(ctx, listKeysOptions)
  if err != nil {
      fmt.Println(err)
  }
  fmt.Println(keys)
}
    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  srtStr, _ := kp.GetKeySortStr(kp.WithCreationDate(), WithImportedDesc())

  listKeysOptions := &kp.ListKeysOptions{
    Sort:srtStr,
  }

  keys, err := client.ListKeys(ctx, listKeysOptions)
  if err != nil {
    fmt.Println(err)
  }

  fmt.Println(keys)
}
    • import os

import keyprotect
from keyprotect import bxauth

# Initialize the Key Protect client as specified in Authentication
keys = kp.keys()
for key in kp.keys():
  print("%s\t%s" % (key["id"], key["name"]))
    • // Initialize the Key Protect client as specified in Authentication

const response = keyProtectClient.getKeys(envConfigs);
console.log('Get keys result:');
for (let resource of response.result.resources){
  console.log(resource);
}
    • public static List<KeyRepresentation> getKeys() {
  GetKeysOptions getKeysOptionsModel = new GetKeysOptions.Builder()
      .bluemixInstance("<instance_id>")
      .build();
  Response<ListKeys> response = testClient.getKeys(getKeysOptionsModel).execute();
  List<KeyRepresentation> keys = response.getResult().getResources();
  return keys;
}

    Response

    Response Body

    ListKeys

    The base schema for listing keys.

    Status Code

    • 200

      The list of keys was successfully retrieved.

    • 400

      If reason code (resouces[0].reasons[0].code) is present and is equal to 'KEY_SEARCH_TOO_BROAD', the total searchable space is more than 5000 keys. Try using a filter to reduce the seachable space.

    • 401

      Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

    • 429

      Too many requests. Wait a few minutes and try again.

    • 500

      IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

    Example responses
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "lastRotateDate": "2000-03-21T00:00:00Z",
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "addedace-0000-0000-0000-1234567890ab",
      "name": "Standard-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:addedace-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "beadcafe-0000-0000-0000-1234567890ab",
      "name": "Deleted-Standard-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 5,
      "extractable": true,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:beadcafe-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": true,
      "deletionDate": "2000-03-21T00:00:00Z",
      "restoreAllowed": true,
      "restoreExpirationDate": "2000-03-21T00:00:00Z",
      "purgeAllowed": false,
      "purgeAllowedFrom": "2000-03-21T00:00:00Z",
      "purgeScheduledOn": "2000-03-21T00:00:00Z"
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

    Retrieve key total

    Returns the same HTTP headers as a GET request without returning the entity-body. This operation returns the number of keys in your instance in a header called Key-Total.

    HEAD /api/v2/keys

    Authorization

    To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

    • kms.secrets.head

    Auditing

    Calling this method generates the following auditing event.

    • kms.secrets.head

    Request

    Custom Headers

    • Bluemix-Instance
      Required*
      string

      The IBM Cloud instance ID that identifies your Key Protect service instance.

      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

    • X-Kms-Key-Ring
      string

      The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

      Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

    Query Parameters

    • state
      integer[]

      The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. Usage: If you want to retrieve active and deleted keys, use ../keys?state=1,5.

      Allowable values: [0,1,2,3,5]

      Possible values: 0 ≤ number of items ≤ 5, 0 ≤ value ≤ 5

      Default: [0,1,2,3]

    • extractable
      boolean

      The type of keys to be retrieved. Filters keys based on the extractable property. You can use this query parameter to search for keys whose material can leave the service. If set to true, standard keys will be retrieved. If set to false, root keys will be retrieved. If omitted, both root and standard keys will be retrieved. Usage: If you want to retrieve standard keys, use ../keys?extractable=true.

    • filter
      string

      When provided, returns the list of keys that match the queried properties. Each key property to be filtered on is specified as the property name itself, followed by an “=“ symbol, and then the value to filter on, followed by a space if there are more properties to filter only. Note: Anything between < and > in the examples or descriptions represent placeholder to specify the value Basic format: = = - The value to filter on may contain a value related to the property itself, or an operator followed by a value accepted by the operator - Only one operator and value, or one value is accepted per property at a time Format with operator/value pair: =: Up to three of the same property may be specified at a time. The key properties that can be filtered at this time are:

      • creationDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • deletionDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • expirationDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • extractable
        • Boolean true or false without quotes, case-insensitive
      • lastRotateDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • lastUpdateDate
        • Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”
      • state
        • A list of comma-separated integers with no space in between: 0,1,2,3,5 Comparison operations (operators) that can be performed on date values are:
      • lte:<value> Less than or equal to - lt:<value> Less than - gte:<value> Greater than or equal to - gt:<value> Greater than A special keyword for date, none (case-insensitive), may be used to retreive keys that do not have that property. This is useful for lastRotateDate, where only keys that have never been rotated can be retreived. Examples:
      • lastRotateDate="2022-02-15T00:00:00Z" Filter keys that were last rotated on February 15, 2022 - lastRotateDate=gte:"2022-02-15T00:00:00Z" Filter keys that were last rotated after or on February 15, 2022 - lastRotateDate=gte:"2022-02-15T00:00:00Z" lastRotateDate=lt:"2022-03-15T00:00:00Z" Filter keys that were last rotated after or on February 15, 2022 but before (not including) March 15, 2022 - lastRotateDate="2022-02-15T00:00:00Z" state=0,1,2,3,5 extractable=false Filter root keys that were last rotated on February 15, 2022, with any state Note: When you filter by state or extractable in this query parameter, you will not be able to use the deprecated state or extractable independent query parameter. You will get a 400 response code if you specify a value for one of the two properties in both this filter query parameter and the deprecated independent query of the same name (the same applies vice versa).

      Possible values: 0 ≤ length ≤ 512, Value must match regular expression ^.{0,512}$

    • curl -I HEAD   https://<region>.kms.cloud.ibm.com/api/v2/keys   -H 'accept: application/vnd.ibm.kms.key+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'

    Response

    Response Headers

    • Key-Total
      integer

      The number of keys in your service instance.

      Possible values: value ≥ 0

    Status Code

    • 200

      The metadata was successfully retrieved.

    • 401

      Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

    • 403

      Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

    • 429

      Too many requests. Wait a few minutes and try again.

    • 500

      IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

    Create a key with policy overrides

    Creates a new key with specified key material and key policies. This API overrides the policy configurations set at instance level with policies provided in the payload. Key Protect designates the resource as a root key or a standard key based on the extractable value that you specify. A successful POST /keys_with_policy_overrides operation adds the key and key policies to the service and returns the details of the request in the response entity-body, if the Prefer header is set to return=representation.

    POST /api/v2/keys_with_policy_overrides

    Authorization

    To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

    • kms.secrets-with-policy-overrides.create

    Auditing

    Calling this method generates the following auditing event.

    • kms.secrets-with-policy-overrides.create

    Request

    Custom Headers

    • Bluemix-Instance
      Required*
      string

      The IBM Cloud instance ID that identifies your Key Protect service instance.

      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

    • Prefer
      string

      Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

      Allowable values: [return=representation,return=minimal]

      Possible values: 14 ≤ length ≤ 21

    • X-Kms-Key-Ring
      string

      The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

      Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

      Default: default

    Request Body

    Required*
    application/vnd.ibm.kms.key+jsonOne of

      The base request for creating a new key with policies.

      Example: 
      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "A Key Protect key"
    }
  ]
}
      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys_with_policy_overrides   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.key+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "type": "application/vnd.ibm.kms.key+json",
        "name": "Root-key",
        "description": "A Key Protect key",
        "extractable": false,
        "dualAuthDelete": {
          "enabled": true
        },
        "rotation":{
          "enabled": true,
          "interval_month": 6
        }
      }
    ]
  }'

      Response

      Response Body

      Key

      Properties associated with a key response.

      Status Code

      • 201

        The key was successfully created.

      • 400

        The key is either missing a required field or it may contain an invalid or malformed input.

      • 401

        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

      • 403

        Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

      • 404

        There are three possible causes for HTTP 404 while trying to create a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

        KEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note the default key ring name is "default." INSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist. IMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist.

      • 409

        The import token that was used to encrypt this key has reached its maxAllowedRetrievals or expirationDate, and it is no longer available for operations. To create a new import token, use POST /import_token. In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to 409 conflict exceptions. KEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached. KEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance. KEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Key Protect only permits the creation or import of keys in your Key Protect instance that follow the key creation and import settings listed on the keyCreateImportAccess policy. IMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.

      • 429

        Too many requests. Wait a few minutes and try again.

      • 500

        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

      Example responses
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      },
      "rotation": {
        "interval_month": 3
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key is missing a required field."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: The import token that was used to encrypt this key has reached its 'maxAllowedRetrievals' or 'expirationDate', and it is no longer available for key operations. To create a new import token, use 'POST /import_token'."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

      Retrieve a key

      Retrieves a key and its details by specifying the ID or alias of the key.

      GET /api/v2/keys/{id}

      Authorization

      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

      • kms.secrets.read

      Auditing

      Calling this method generates the following auditing event.

      • kms.secrets.read

      Request

      Custom Headers

      • Bluemix-Instance
        Required*
        string

        The IBM Cloud instance ID that identifies your Key Protect service instance.

        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

      • Correlation-Id
        string

        The v4 UUID used to correlate and track transactions.

        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

      • X-Kms-Key-Ring
        string

        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

      Path Parameters

      • id
        Required*
        string

        The v4 UUID or alias that uniquely identifies the key.

        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>   -H 'accept: application/vnd.ibm.kms.key+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  key, err := api.GetKey(context.Background(), <key_ID_or_alias>)
  if err != nil {
    fmt.Println("Error while retrieving the key: ", err)
    return
  }
  b, _ := json.MarshalIndent(key, "", "  ")
  fmt.Println(string(b))
}
      • // Initialize the Key Protect client as specified in Authentication

const getKeyParams = Object.assign({}, envConfigs);
getKeyParams.id = "<key_id>";
const response = keyProtectClient.getKey(getKeyParams);
console.log('Get key result: ');
console.log(response.result.resources[0]);
      • import os

import keyprotect
from keyprotect import bxauth

# Initialize the Key Protect client as specified in Authentication
key = kp.get("<key_id>")
print("%s\t%s" % (key["id"], key["name"]))
      • public static List<KeyWithPayload> getKey(String keyId) {
  GetKeyOptions getKeyOptionsModel = new GetKeyOptions.Builder()
      .bluemixInstance("<instance_id>")
      .id(keyId)
      .build();
  Response<GetKey> response = testClient.getKey(getKeyOptionsModel).execute();
  List<KeyWithPayload> key = response.getResult().getResources();
  return key;
}

      Response

      Response Body

      GetKey

      The base schema for retrieving keys.

      Status Code

      • 200

        The key was successfully retrieved. If the key was previously deleted, keyVersion.creationDate is omitted from the request response.

      • 400

        The key could not be retrieved due to a malformed, invalid, or missing ID.

      • 401

        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

      • 403

        Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

      • 404

        The key could not be found. Verify that the key ID specified is valid.

      • 429

        Too many requests. Wait a few minutes and try again.

      • 500

        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

      Example responses
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Standard-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false,
      "payload": "x089YbmN9GSvpxEKe0LaqA=="
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key could not be retrieved due to a malformed, invalid, or missing ID."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. Verify that the key ID specified is valid."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

      Invoke an action on a key

      Note: This API has been deprecated and transitioned to individual request paths. Existing actions using this API will continue to be supported, but new actions will no longer be added to it. We recommend, if possible, aligning your request URLs to the new API path. The generic format of actions is now the following: /api/v2/keys/<key_ID>/actions/<action> where key_ID is the key you want to operate on/with and action is the same action that was passed as a query parameter previously.

      Invokes an action on a specified key. This method supports the following actions:

      Note: If you unwrap a wrapped data encryption key (WDEK) that was not wrapped by the latest version of the key, the service also returns the a new WDEK, wrapped with the latest version of the key as the ciphertext field. The recommendation is to store and use that WDEK, although older WDEKs will continue to work.

      POST /api/v2/keys/{id}

      Authorization

      To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

      • kms.secrets.disable

      • kms.secrets.enable

      • kms.secrets.restore

      • kms.secrets.rewrap

      • kms.secrets.rotate

      • kms.secrets.setkeyfordeletion

      • kms.secrets.unsetkeyfordeletion

      • kms.secrets.unwrap

      • kms.secrets.wrap

      Auditing

      Calling this method generates the following auditing events.

      • kms.secrets.disable

      • kms.secrets.enable

      • kms.secrets.restore

      • kms.secrets.rewrap

      • kms.secrets.rotate

      • kms.secrets.setkeyfordeletion

      • kms.secrets.unsetkeyfordeletion

      • kms.secrets.unwrap

      • kms.secrets.wrap

      Request

      Custom Headers

      • Bluemix-Instance
        Required*
        string

        The IBM Cloud instance ID that identifies your Key Protect service instance.

        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

      • Correlation-Id
        string

        The v4 UUID used to correlate and track transactions.

        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

      • X-Kms-Key-Ring
        string

        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

      • Prefer
        string

        Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

        Allowable values: [return=representation,return=minimal]

        Possible values: 14 ≤ length ≤ 21

      Path Parameters

      • id
        Required*
        string

        The v4 UUID that uniquely identifies the key.

        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

      Query Parameters

      • action
        Required*
        string

        The action to perform on the specified key.

        Allowable values: [disable,enable,restore,rewrap,rotate,setKeyForDeletion,unsetKeyForDeletion,unwrap,wrap]

        Possible values: 4 ≤ length ≤ 19

      Request Body

      Required*
      application/vnd.ibm.kms.key_action+jsonOne of

        The base request for key actions.

        Example:

        Wrap key

        {
  "plaintext": "<data_key>",
  "aad": [
    "<additional_data>",
    "<additional_data>"
  ]
}

        Response

        Response Body

        One of

          Properties that are associated with the response body of a wrap action.

          Status Code

          • 200

            Successful key operation.

          • 201

            The imported key was successfully restored.

          • 204

            Successful key operation.

          • 400

            Your authentication data or key is invalid, or the entity-body is missing a required field.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 403

            Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

          • 404

            The key could not be found.

          • 409

            The key is not in an appropriate state, so the KeyAction has failed.

          • 410

            The requested key was previously deleted and is no longer available. Delete references to this key.

          • 422

            The ciphertext provided for the unwrap operation was not wrapped by this key.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=",
  "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9",
  "keyVersion": {
    "id": "fadedbee-0000-0000-0000-1234567890ab"
  }
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": false,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": true,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Your authentication data or key is invalid, or the entity-body is missing a required field."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: The key is not in an appropriate state, so the KeyAction has failed."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unprocessable Entity: The ciphertext provided for the unwrap operation was not wrapped by this key."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Update (patch) a key

          Update attributes of a key. Currently only the following attributes are applicable for update: - keyRingID Note: If provided, the X-Kms-Key-Ring header should specify the key's current key ring. To change the key ring of the key, specify the new key ring in the request body.

          PATCH /api/v2/keys/{id}

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.patch

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.patch

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          Path Parameters

          • id
            Required*
            string

            The v4 UUID that uniquely identifies the key.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          Request Body

          application/vnd.ibm.kms.key+jsonPatchKeyRequestBody

          The base request for patch key.

          Examples: 
          {
  "keyRingID": "new-key-ring-id"
}
          • curl -X PATCH   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>   -H 'accept: application/vnd.ibm.kms.key+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key+json'   -d '{
    "keyRingID": "new-key-ring"
  }'
          • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  keyDetails, err := api.SetKeyRing(context.Background(), <key_ID>, <new_key_ring_name>)
  if err != nil {
    fmt.Println("Error while updating the key: ", err)
    return
  }
  b, _ := json.MarshalIndent(keyDetails, "", "  ",)
  fmt.Println(string(b))
}

          Response

          Response Body

          PatchKeyResponseBody

          The base schema for patch key response body.

          Status Code

          • 200

            Successful key update.

          • 400

            The request is missing a required field.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 404

            There are two possible causes for HTTP 404 while trying to update a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. KEY_RING_NOT_FOUND_ERR: Key could not be updated, key ring specified does not exist.

          • 410

            The requested key was previously deleted and is no longer available. Delete references to this key.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": false,
      "keyRingID": "new-key-ring-id",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The request is missing a required field."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be restored. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Delete a key

          Deletes a key by specifying the ID or alias of the key.

          By default, Key Protect requires a single authorization to delete keys. For added protection, you can enable a dual authorization policy to safely delete keys from your service instance.

          Important: After a key has been deleted, any data that is encrypted by the key becomes inaccessible, though this can be reversed if the key is restored within the 30-day time frame. After 30 days, key metadata, registrations, and policies are available for up to 90 days, at which point the key becomes eligible to be purged. Note that once a key is no longer restorable and has been purged, its associated data can no longer be accessed.

          Note: By default, Key Protect blocks the deletion of a key that's protecting a cloud resource, such as a Cloud Object Storage bucket. Use GET keys/{id}/registrations to verify if the key has an active registration to a resource. To delete the key and its associated registrations, set the optional force parameter to true.

          DELETE /api/v2/keys/{id}

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.delete

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.delete

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          • Prefer
            string

            Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

            Allowable values: [return=representation,return=minimal]

            Possible values: 14 ≤ length ≤ 21

          Path Parameters

          • id
            Required*
            string

            The v4 UUID that uniquely identifies the key.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          Query Parameters

          • force
            boolean

            If set to true, Key Protect forces deletion on a key that is protecting a cloud resource, such as a Cloud Object Storage bucket. The action removes any registrations that are associated with the key. Note: If a key is protecting a cloud resource that has a retention policy, Key Protect cannot delete the key. Use GET keys/{id}/registrations to review registrations between the key and its associated cloud resources. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.

            Default: false

          • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>   -H 'accept: application/vnd.ibm.kms.key+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
          • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  force := false // set this to true if force-delete is needed
  delKey, err := client.DeleteKey(context.Background(), key.ID, kp.ReturnRepresentation, kp.ForceOpt{Force: force})
  if err != nil {
    fmt.Println("Error while deleting the key: ", err)
    return
  }
  b, _ := json.MarshalIndent(delKey, "", "  ")
  fmt.Println(string(b))
}
          • // Initialize the Key Protect client as specified in Authentication

const deleteKeyParams = Object.assign({}, envConfigs);
deleteKeyParams.id = "<key_ID_or_alias>";
deleteKeyParams.prefer = 'return=representation';
const response = keyProtectClient.deleteKey(deleteKeyParams);
console.log('Delete key response status: ' + response.status);
          • import os

import keyprotect
from keyprotect import bxauth

# Initialize the Key Protect client as specified in Authentication
deletedKey = kp.delete("<key_id>")
print("Deleted key '%s'" % key_id)
          • public static DeleteKey deleteKey(String keyId, Boolean forceDelete) {
  
  Boolean deleteForceParam = false;
  if (forceDelete != null) {
    deleteForceParam = forceDelete;
  }
  
  DeleteKeyOptions deleteKeyOptionsModel = new DeleteKeyOptions.Builder()
      .bluemixInstance("<instance_id>")
      .id(keyId)
      .force(deleteForceParam)
      .build();
  Response<DeleteKey> response = testClient.deleteKey(deleteKeyOptionsModel).execute();
  DeleteKey result = response.getResult();
  return result; // null result on success 
}

          Response

          Response Body

          DeleteKey

          The base schema for deleting keys.

          Status Code

          • 200

            The key was successfully deleted. The status code is the only response, unless the prefer parameter contains return=representation.

          • 204

            The key was successfully deleted. No content. The status code is the only response, unless the prefer parameter contains return=representation.

          • 400

            The key cannot be deleted due to a malformed, invalid, or missing ID.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 403

            Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

          • 404

            The key could not be found.

          • 409

            There are three possible causes for HTTP 409 while trying to delete a key, specifying a reason code (resouces[0].reasons[0].code) as follows:

            AUTHORIZATIONS_NOT_MET: The key cannot be deleted because it failed the dual authorization request. Before you delete this key, make sure dual authorization procedures are followed. See the topic, Deleting keys using dual authorization.

            PROTECTED_RESOURCE_ERR: The key cannot be deleted because the key has one or more associated resources. See the topic, Considerations before deleting and purging a key.

            PREV_KEY_DEL_ERR: The key cannot be deleted because it's protecting a cloud resource that has a retention policy. Before you delete this key, contact an account owner to remove the retention policy on each resource that is associated with the key. See the topic, Considerations before deleting and purging a key.

          • 410

            The requested key was previously deleted and is no longer available. Delete references to this key.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 5,
      "extractable": false,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "lastRotateDate": "2000-03-21T00:00:00Z",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": true,
      "deletionDate": "2000-03-21T00:00:00Z",
      "deletedBy": "IBMid-0000000000",
      "restoreAllowed": true,
      "restoreExpirationDate": "2000-03-21T00:00:00Z",
      "purgeAllowed": false,
      "purgeAllowedFrom": "2000-03-21T00:00:00Z",
      "purgeScheduledOn": "2000-03-21T00:00:00Z"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key cannot be deleted due to a malformed, invalid, or missing ID."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key could not be deleted. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "PREV_KEY_DEL_ERR",
          "message": "The key cannot be deleted because it's protecting a cloud resource that has a retention policy. Before you delete this key, contact an account owner to remove the retention policy on each resource that is associated with the key.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Retrieve key metadata

          Retrieves the details of a key by specifying the ID of the key.

          GET /api/v2/keys/{id}/metadata

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.readmetadata

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets-metadata.read

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/metadata   -H 'accept: application/vnd.ibm.kms.key+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
          • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  keyMetadata, err := api.GetKeyMetadata(context.Background(), <key_ID|alias>)
  if err != nil {
    fmt.Println("Error while retrieving key metadata: ", err)
    return
  }
  b, _ := json.MarshalIndent(keyMetadata, "", "  ")
  fmt.Println(string(b))
}
          • public static GetKeyMetadata getKeyMetadata(String keyId) {
  GetKeyMetadataOptions getKeyMetadataOptionsModel = new GetKeyMetadataOptions.Builder()
            .id(keyId)
            .bluemixInstance("<instance_id>")
            .build();
    Response<GetKeyMetadata> response = testClient.getKeyMetadata(getKeyMetadataOptionsModel).execute();
    GetKeyMetadata metadata = response.getResult();
    
    return metadata;
}

          Response

          Response Body

          GetKeyMetadata

          The base schema for retrieving key metadata.

          Status Code

          • 200

            The key metadata was successfully retrieved.

          • 400

            The key metadata could not be retrieved due to a malformed, invalid, or missing ID or alias.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 403

            Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

          • 404

            The key metadata for the key with specified ID could not be found.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Standard-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key metadata could not be retrieved due to a malformed, invalid, or missing ID."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key metadata could not be retrieved. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Purge a deleted key

          Purges all key metadata and registrations associated with the specified key. This method requires setting the KeyPurge permission that is not enabled by default. Purging a key can only be applied to a key in the Destroyed (5) state. After a key is deleted, there is a wait period of up to four hours before purge key operation is allowed. Important: When you purge a key, you permanently shred its contents and associated data. The action cannot be reversed.

          DELETE /api/v2/keys/{id}/purge

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.purge

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.purge

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          • Prefer
            string

            Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

            Allowable values: [return=representation,return=minimal]

            Possible values: 14 ≤ length ≤ 21

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/purge   -H 'accept: application/vnd.ibm.kms.key+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
          • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  purgedKey, err := api.PurgeKey(context.Background(), <key_ID>, kp.ReturnRepresentation)
  if err != nil {
    fmt.Println("Error while purging key : ", err)
    return
  }
  b, _ := json.MarshalIndent(purgedKey, "", "  ")
  fmt.Println(string(b))
}

          Response

          Response Body

          PurgeKey

          The base schema for purged key.

          Status Code

          • 200

            The key was successfully purged.

          • 204

            The key was successfully purged. No content.

          • 400

            The key cannot be purged due to a malformed ID.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 403

            Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

          • 404

            The key could not be found.

          • 409

            There are two possible causes for HTTP 409 while trying to delete a key, specifying a reason code (resouces[0].reasons[0].code) as follows: REQ_TOO_EARLY_ERR: The key could not be purged due to wait period of four hours has not been reached. KEY_ACTION_INVALID_STATE_ERR: The key could not be purged because it is not in the Destroyed (5) state.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 5,
      "extractable": false,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": false,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "lastRotateDate": "2000-03-21T00:00:00Z",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": true,
      "deletionDate": "2000-03-21T00:00:00Z",
      "deletedBy": "IBMid-0000000000",
      "purgeAllowed": true,
      "purgeAllowedFrom": "2000-03-21T00:00:00Z",
      "purgeScheduledOn": "2000-03-21T00:00:00Z"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key cannot be purged due to a malformed ID."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key could not be purged. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_INVALID_STATE_ERR",
          "message": "Key is not in a valid state.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Restore a key

          Restore a key that has been deleted.

          POST /api/v2/keys/{id}/restore

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.restore

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.restore

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          • Prefer
            string

            Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

            Allowable values: [return=representation,return=minimal]

            Possible values: 14 ≤ length ≤ 21

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          Request Body

          Required*
          application/vnd.ibm.kms.key_action_restore+jsonRestoreKeyRequestBody

          The base request parameters for restore key action.

          Examples: 
          {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "payload": "x089YbmN9GSvpxEKe0LaqA=="
    }
  ]
}
          {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "payload": "x089YbmN9GSvpxEKe0LaqA==",
      "encryptionAlgorithm": "RSAES_OAEP_SHA_256",
      "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==",
      "iv": "puQrzDX7gU1TcTTx"
    }
  ]
}
          • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/restore   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_restore+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.key_action_restore+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "payload": "<key_material>"
      }
    ]
  }'
          • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/restore   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_restore+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.key_action_restore+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "payload": "<encrypted_key_material>",
        "encryptedNonce": "<encrypted_nonce>",
        "iv": "<iv>",
        "encryptionAlgorithm": "RSAES_OAEP_SHA_256"
      }
    ]
  }'
          • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  restoredKey, err := api.RestoreKey(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while restoring key: ", err)
    return
  }
  b, _ := json.MarshalIndent(restoredKey, "", "  ")
  fmt.Println(string(b))
}
          • public static KeyActionOneOfResponse restoreKey(String keyId) {
  InputStream inputStream = null;
  ActionOnKeyOptions restoreKeyOptionsModel = null;
  Response<KeyActionOneOfResponse> response = null;
  KeyActionOneOfResponse responseObj = null;

  try {
    // Only imported root keys can be restored; if the file conforms to the
    // SecureRestoreKeyRequestBody format, include the encryption method,
    // encrypted payload, encrypted nonce, and initialization vector.
    inputStream = new FileInputStream("/path/to/file.txt");
    restoreKeyOptionsModel = new ActionOnKeyOptions.Builder()
            .id(keyId)
            .bluemixInstance("<INSTANCE_ID>")
            .action("restore")
            .keyActionOneOf(inputStream)
            .prefer("return=minimal")
            .build();
  }  catch(FileNotFoundException e) {
    System.out.println("File not found: " + e.toString());
    return responseObj;
  }

    response = testClient.actionOnKey(restoreKeyOptionsModel).execute();
    responseObj = response.getResult();
    return responseObj;
}

          Response

          Response Body

          Key

          Properties associated with a key response.

          Status Code

          • 201

            The key was successfully restored.

          • 400

            The request is missing a required field.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 404

            The key could not be found.

          • 409

            There are three possible causes for HTTP 409 while trying to restore a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the Destroyed (5) state. REQ_TOO_EARLY_ERR: Key could not be restored. The key was updated recently, wait and try again. Restoring a key is only allowed when 30 seconds after key is deleted has passed. KEY_RING_RESOURCE_QUOTA_ERR: Key could not be restored. The resource quota for key rings in this instance has been reached and key rings cannot be created.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "name": "Root-key",
      "aliases": [
        "alias-for-this-key"
      ],
      "description": "A Key Protect key",
      "state": 1,
      "extractable": false,
      "keyRingID": "default",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:key:fadedbee-0000-0000-0000-1234567890ab",
      "imported": true,
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000",
      "algorithmType": "Deprecated",
      "algorithmMetadata": {
        "bitLength": "256",
        "mode": "Deprecated"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "Deprecated",
      "lastUpdateDate": "2000-03-21T00:00:00Z",
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "2000-03-21T00:00:00Z"
      },
      "deleted": false
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The request is missing a required field."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be restored. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be restored. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ACTION_INVALID_STATE_ERR",
          "message": "Key is not in a valid state.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          List key versions

          Retrieves all versions of a root key by specifying the ID or alias of the key.

          When you rotate a root key, you generate a new version of the key. If you're using the root key to protect resources across IBM Cloud, the registered cloud services that you associate with the key use the latest key version to wrap your data. Learn more.

          GET /api/v2/keys/{id}/versions

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.listkeyversions

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets-key-versions.list

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          Query Parameters

          • limit
            integer

            The number of key versions to retrieve. By default, GET /versions returns the first 200 key versions. To retrieve a different set of key versions, use limit with offset to page through your available resources. The maximum value for limit is 5,000. Usage: If you have a key with 20 versions in your instance, and you want to retrieve only the first 5 versions, use ../versions?limit=5.

            Possible values: 1 ≤ value ≤ 5000

            Default: 200

          • offset
            integer

            The number of key versions to skip. By specifying offset, you retrieve a subset of key versions that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have a key with 100 versions in your instance, and you want to retrieve versions 26 through 50, use ../versions?offset=25&limit=25.

            Possible values: value ≥ 0

            Default: 0

          • totalCount
            boolean

            If set to true, returns totalCount in the response metadata for use with pagination. The totalCount value returned specifies the total number of key versions that match the request, disregarding limit and offset. The default is set to false. Usage: To return the totalCount value for use with pagination, use ../versions?totalCount=true.

          • allKeyStates
            boolean

            If set to true, returns the key versions of a key in any state. Usage: If you have deleted a key and still want to retrieve its key versions use ../versions?allKeyStates=true.

            Default: false

          • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/versions   -H 'accept: application/vnd.ibm.kms.key.version+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
          • public static List<KeyVersion> getKeyVersions(String keyId) {
  GetKeyVersionsOptions getKeyVersionsOptionsModel = new GetKeyVersionsOptions.Builder()
              .id(keyId)
              .bluemixInstance("<instance_id>")
              .build();
  Response<ListKeyVersions> response = testClient.getKeyVersions(getKeyVersionsOptionsModel ).execute();
  List<KeyVersion> details = response.getResult().getResources();
  return details;
}
          • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  limit := uint32(2)
  offset := uint32(0)
  totalCount := true

  listkeyVersionsOptions := &kp.ListKeyVersionsOptions{
    Limit : &limit,
    Offset : &offset,
    TotalCount : &totalCount,
  }

  keyVersions, err := client.ListKeyVersions(ctx, "key_id_or_alias", listkeyVersionsOptions)
  if err != nil {
    fmt.Println(err)
  }

  fmt.Println(keyVersions)
}

          Response

          Response Body

          ListKeyVersions

          Properties associated with a registration response.

          Status Code

          • 200

            The list of key versions was successfully retrieved.

          • 400

            The request is missing a required field.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 404

            The key could not be found.

          • 409

            The key is not in an active state.

          • 410

            The requested key was previously deleted and is no longer available. Delete references to this key.

          Example responses
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 2,
    "totalCount": 4
  },
  "resources": [
    {
      "id": "fadedbee-0000-0000-0000-1234567890ab",
      "creationDate": "2000-03-21T00:00:00Z"
    },
    {
      "id": "addedace-0000-0000-0000-1234567890ab",
      "creationDate": "2000-03-21T00:00:00Z"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The request is missing a required field."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist"
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: The key is not in an active state."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key."
    }
  ]
}

          Wrap a key

          Use a root key to wrap or encrypt a data encryption key. When present, the ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect.

          POST /api/v2/keys/{id}/actions/wrap

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.wrap

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.wrap

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          Request Body

          application/vnd.ibm.kms.key_action_wrap+jsonWrapKeyRequestBody

          The base request for wrap key action.

          Examples: 
          {
  "plaintext": "<data_key>",
  "aad": [
    "<additional_data>",
    "<additional_data>"
  ]
}
          • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/wrap   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_wrap+json'
          • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/actions/wrap   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_wrap+json'   -d '{
    "plaintext": "<data_key>",
    "aad": ["<additional_data>", "<additional_data>"]
  }'
          • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  aad := []string{"<additional_data>", "<additional_data>"}
  plaintext := []byte(<data_key>)
  ciphertext, err := api.Wrap(context.Background(), <key_ID>, plaintext, &aad)
  if err != nil {
    fmt.Println("Error wrapping the key: ", err)
    return
  }
  fmt.Println(string(ciphertext))
}
          • // Initialize the Key Protect client as specified in Authentication

// Wrap and unwrap base64 encoded plaintext using key
const samplePlaintext = 'dGhpcyBpcyBhIGJhc2U2NCBzdHJpbmcK'; // base64 encoded plaintext

const wrapKeyParams = Object.assign({}, envConfigs);
wrapKeyParams.id = "<key_ID_or_alias>";
wrapKeyParams.keyActionWrapBody = {
  plaintext: samplePlaintext,
};

const response = keyProtectClient.wrapKey(wrapKeyParams);
console.log('Wrap key response cipher: ' + response.result.ciphertext);
const ciphertextResult = response.result.ciphertext; // saved for the unwrap example
          • import os

import keyprotect
from keyprotect import bxauth

# Initialize the Key Protect client as specified in Authentication

key = kp.create(name="MyRootKey", root=True)

# payload should be a bytestring
message = b'This is an important test message.'
wrapped = kp.wrap(key.get('id'), message)
ciphertext = wrapped.get("ciphertext")

          Response

          Response Body

          WrapKeyResponseBody

          Properties that are associated with the response body of a wrap action.

          Status Code

          • 200

            The key was successfully wrapped.

          • 400

            The request is malformed or illegal.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 404

            The key could not be found.

          • 409

            The key is not in the Active (1) state.

          • 410

            The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=",
  "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9",
  "keyVersion": {
    "id": "fadedbee-0000-0000-0000-1234567890ab"
  }
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Wrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field 'plaintext' must be a base64 encoded key material.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "plaintext"
          }
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Wrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist.",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Wrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ACTION_INVALID_STATE_ERR",
          "message": "Key is not in a valid state.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Wrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Unwrap a key

          Use a root key to unwrap or decrypt a data encryption key.

          Note: When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available for unwrap actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext and latest key version in the response. Use the latest ciphertext for future unwrap operations.

          POST /api/v2/keys/{id}/actions/unwrap

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.unwrap

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.unwrap

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          Request Body

          Required*
          application/vnd.ibm.kms.key_action_unwrap+jsonUnwrapKeyRequestBody

          The base request for unwrap key action.

          Examples: 
          {
  "ciphertext": "<encrypted_data_key>",
  "aad": [
    "<additional_data>",
    "<additional_data>"
  ]
}
          • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/unwrap   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_unwrap+json'   -d '{
    "ciphertext": "<encrypted_data_key>",
    "aad": ["<additional_data>", "<additional_data>"]
  }'
          • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  aad := []string{"<additional_data>", "<additional_data>"}
  ciphertext := []byte(<encrypted_data_key>)
  pt2, err := api.Unwrap(context.Background(), <key_ID>, ciphertext, &aad)
  if err != nil {
    fmt.Println("Error while unwrapping DEK: ", err)
    return
  }
  b, _ := json.MarshalIndent(pt2, "", "  ")
  fmt.Println(string(b))
}
          • // Initialize the Key Protect client as specified in Authentication

const unwrapKeyParams = Object.assign({}, envConfigs);
unwrapKeyParams.id = "<key_ID_or_alias>";
unwrapKeyParams.keyActionUnwrapBody = {
  ciphertext: ciphertextResult, // encrypted result from wrap key response
};
const response = keyProtectClient.unwrapKey(unwrapKeyParams);
console.log('Unwrap key response result: ' + response.result.plaintext); // validate that result is same as above
          • import os

import keyprotect
from keyprotect import bxauth

# Continue from example for wrap key
# key = kp.create(name="MyRootKey", root=True)
# message = b'This is a really important message.'

unwrapped = kp.unwrap(key.get('id'), ciphertext)
assert message == unwrapped

          Response

          Response Body

          UnwrapKeyResponseBody

          Properties that are associated with the response body of an unwrap action.

          Status Code

          • 200

            Successfully unwrapped key.

          • 400

            The request is malformed or illegal.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 404

            The key could not be found.

          • 409

            The key is not in the Active (1) or Deactivated (3) state.

          • 410

            The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

          • 422

            The ciphertext provided was not wrapped by this key.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=",
  "keyVersion": {
    "id": "fadedbee-0000-0000-0000-1234567890ab"
  }
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Unwrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "MISSING_FIELD_ERR",
          "message": "The field 'ciphertext' is required.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "name"
          }
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Unwrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Wrap action could not be performed with the key. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ACTION_INVALID_STATE_ERR",
          "message": "Key is not in a valid state",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Unwrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unprocessable Entity: Unwrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "UNPROCESSABLE_CIPHERTEXT_ERR",
          "message": "The provided ciphertext is invalid or corrupted.",
          "status": 422,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Rewrap a key

          Use a root key to rewrap or reencrypt a data encryption key.

          POST /api/v2/keys/{id}/actions/rewrap

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.rewrap

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.rewrap

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          Request Body

          Required*
          application/vnd.ibm.kms.key_action_rewrap+jsonRewrapKeyRequestBody

          The base request for rewrap key action.

          Examples: 
          {
  "ciphertext": "<encrypted_data_key>",
  "aad": [
    "<additional_data>",
    "<additional_data>"
  ]
}
          • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/rewrap   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_rewrap+json'   -d '{
    "ciphertext": "<encrypted_data_key>",
    "aad": ["<additional_data>", "<additional_data>"]
  }'

          Response

          Response Body

          RewrapKeyResponseBody

          Properties that are associated with the response body of an rewrap action.

          Status Code

          • 200

            The key was successfully rewrapped.

          • 400

            The request is malformed or illegal.

          • 401

            Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

          • 404

            The key could not be found.

          • 409

            The key is not in the Active (1) or Deactivated (3) state.

          • 410

            The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

          • 422

            The ciphertext provided was not wrapped by this key.

          • 429

            Too many requests. Wait a few minutes and try again.

          • 500

            IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

          Example responses
          • {
  "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9",
  "keyVersion": {
    "id": "fadedbee-0000-0000-0000-1234567890ab"
  },
  "rewrappedKeyVersion": {
    "id": "addedace-0000-0000-0000-1234567890ab"
  }
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Rewrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field 'ciphertext' must be the original base64 encoded ciphertext from the wrap operation.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "ciphertext"
          }
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Rewrap with key could not be performed.  See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Rewrap with key could not be performed.  See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ACTION_INVALID_STATE_ERR",
          "message": "Key is not in a valid state.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Rewrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unprocessable Entity: Rewrap with key could not be performed. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "UNPROCESSABLE_CIPHERTEXT_ERR",
          "message": "The provided ciphertext is invalid or corrupted",
          "status": 422,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
          • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

          Rotate a key

          Create a new version of a root key.

          POST /api/v2/keys/{id}/actions/rotate

          Authorization

          To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

          • kms.secrets.rotate

          Auditing

          Calling this method generates the following auditing event.

          • kms.secrets.rotate

          Request

          Custom Headers

          • Bluemix-Instance
            Required*
            string

            The IBM Cloud instance ID that identifies your Key Protect service instance.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • Correlation-Id
            string

            The v4 UUID used to correlate and track transactions.

            Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

          • X-Kms-Key-Ring
            string

            The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

            Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

          • Prefer
            string

            Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

            Allowable values: [return=representation,return=minimal]

            Possible values: 14 ≤ length ≤ 21

          Path Parameters

          • id
            Required*
            string

            The v4 UUID or alias that uniquely identifies the key.

            Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

          Request Body

          application/vnd.ibm.kms.key_action_rotate+jsonOne of

            The base request for rotate key action.

            Example:

            Rotate key

            {
  "payload": "aQFr+ry+ThyyHsV0QnyVOg=="
}
            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/rotate   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/actions/rotate   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_rotate+json'   -d '{
    "payload": "<new_key_material>"
  }'
            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/actions/rotate   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.key_action_rotate+json'   -d '{
    "payload": "<encrypted_new_key_material>",
    "encryptedNonce": "<encrypted_nonce>",
    "iv": "<iv>",
    "encryptionAlgorithm": "RSAES_OAEP_SHA_256"
  }'
            • package main

import (
 "context"
 "fmt"

 kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  // Set the payload to a base64 encoded string if your key is an imported root key
  // Skip setting payload if your key is a generated root key
  payload := "<new_key_material>"
  err = api.Rotate(context.Background(), <key_ID> , payload)
  if err != nil {
    fmt.Println("Error rotating the key: ", err)
    return
  }
  fmt.Println("Key successfully rotated")
}

            Response

            Status Code

            • 204

              The key was successfully rotated. No content.

            • 400

              The request is malformed or illegal.

            • 401

              Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

            • 404

              There are three possible causes for HTTP 404 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. INSTANCE_NOT_FOUND_ERR: Key could not be rotated, specified instance does not exist. IMPORT_TOKEN_NOT_FOUND_ERR: Key could not be rotated, import_token does not exist.

            • 409

              There are four possible causes for HTTP 409 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the Active (1) or Deactivated (3) state. KEY_ROTATION_NOT_PERMITTED: Key could not be rotated, this key has been rotated within the last hour, only one rotate action per hour is permitted. KEY_CREATE_IMPORT_ACCESS_ERR: Instance policy does not allow this action. IMPORT_TOKEN_EXPIRED_ERR: Key could not be rotated, the import token has expired.

            • 410

              The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

            • 429

              Too many requests. Wait a few minutes and try again.

            • 500

              IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

            Example responses
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Key could not be rotated. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field 'payload' must be: a base64 encoded value",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "payload"
          }
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be rotated. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be rotated. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ACTION_INVALID_STATE_ERR",
          "message": "Key is not in a valid state",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key could not be rotated. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

            Set a key for deletion

            Authorize deletion for a key with a dual authorization policy.

            POST /api/v2/keys/{id}/actions/setKeyForDeletion

            Authorization

            To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

            • kms.secrets.setkeyfordeletion

            Auditing

            Calling this method generates the following auditing event.

            • kms.secrets.setkeyfordeletion

            Request

            Custom Headers

            • Bluemix-Instance
              Required*
              string

              The IBM Cloud instance ID that identifies your Key Protect service instance.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • Correlation-Id
              string

              The v4 UUID used to correlate and track transactions.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • X-Kms-Key-Ring
              string

              The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

              Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

            Path Parameters

            • id
              Required*
              string

              The v4 UUID or alias that uniquely identifies the key.

              Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/setKeyForDeletion   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
            • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err := api.InitiateDualAuthDelete(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while initiating dual auth delete for key: ", err)
    return
  }
  fmt.Println("Key successfully initiated for dual auth delete")
}

            Response

            Status Code

            • 204

              The key was successfully set for deletion. No content.

            • 400

              The request is missing a required field.

            • 401

              Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

            • 404

              There are two possible causes for HTTP 404 while trying to set a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.

            • 409

              The key does not have a dual-authorization delete policy.

            • 410

              The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

            • 429

              Too many requests. Wait a few minutes and try again.

            • 500

              IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

            Example responses
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The request is missing a required field."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key deletion could not be scheduled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key deletion could not be scheduled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "NOT_DUAL_AUTH_ERR",
          "message": "The key is not dual auth enabled and cannot be set for deletion.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key deletion could not be scheduled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

            Unset a key for deletion

            Remove an authorization for a key with a dual authorization policy.

            POST /api/v2/keys/{id}/actions/unsetKeyForDeletion

            Authorization

            To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

            • kms.secrets.unsetkeyfordeletion

            Auditing

            Calling this method generates the following auditing event.

            • kms.secrets.unsetkeyfordeletion

            Request

            Custom Headers

            • Bluemix-Instance
              Required*
              string

              The IBM Cloud instance ID that identifies your Key Protect service instance.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • Correlation-Id
              string

              The v4 UUID used to correlate and track transactions.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • X-Kms-Key-Ring
              string

              The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

              Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

            Path Parameters

            • id
              Required*
              string

              The v4 UUID or alias that uniquely identifies the key.

              Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/unsetKeyForDeletion   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
            • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err := api.CancelDualAuthDelete(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while cancelling dual auth delete for key: ", err)
    return
  }
  fmt.Println("Key successfully cancelled for dual auth delete")
}

            Response

            Status Code

            • 204

              The key was successfully unset for deletion. No content.

            • 400

              The request is missing a required field.

            • 401

              Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

            • 404

              There are two possible causes for HTTP 404 while trying to unset a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.

            • 409

              The key does not have a dual-authorization delete policy.

            • 410

              The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

            • 429

              Too many requests. Wait a few minutes and try again.

            • 500

              IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

            Example responses
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The request is missing a required field."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key deletion could not be cancelled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key deletion could not be cancelled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "NOT_DUAL_AUTH_ERR",
          "message": "The key is not dual auth enabled and cannot be set for deletion",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key deletion could not be cancelled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

            Enable a key

            Enable operations for a key.

            POST /api/v2/keys/{id}/actions/enable

            Authorization

            To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

            • kms.secrets.enable

            Auditing

            Calling this method generates the following auditing event.

            • kms.secrets.enable

            Request

            Custom Headers

            • Bluemix-Instance
              Required*
              string

              The IBM Cloud instance ID that identifies your Key Protect service instance.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • Correlation-Id
              string

              The v4 UUID used to correlate and track transactions.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • X-Kms-Key-Ring
              string

              The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

              Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

            Path Parameters

            • id
              Required*
              string

              The v4 UUID or alias that uniquely identifies the key.

              Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/enable   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
            • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err := api.EnableKey(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while enabling the key: ", err)
    return
  }
  fmt.Println("Key successfully enabled")
}

            Response

            Status Code

            • 204

              The key was successfully enabled. No content.

            • 400

              The request is malformed or illegal.

            • 401

              Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

            • 404

              The key could not be found.

            • 409

              There are two possible causes for HTTP 409 while trying to enable a key, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_ACTION_INVALID_STATE_ERR: The requested key is not in the Suspended (2) state or the state of the key has changed within the last 30 seconds. REQ_TOO_EARLY_ERR: Key could not be enabled, as the key was updated recently. After key is disabled, the event must fully propagate before enabling key operations. Wait and try again.

            • 410

              The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

            • 429

              Too many requests. Wait a few minutes and try again.

            • 500

              IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

            Example responses
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Key could not be enabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ROOT_REQ_ERR",
          "message": "Requested action can only be completed with a root key.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be enabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist.",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be enabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ACTION_INVALID_STATE_ERR",
          "message": "Key is not in a valid state",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key could not be enabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

            Disable a key

            Disable operations for a key.

            POST /api/v2/keys/{id}/actions/disable

            Authorization

            To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

            • kms.secrets.disable

            Auditing

            Calling this method generates the following auditing event.

            • kms.secrets.disable

            Request

            Custom Headers

            • Bluemix-Instance
              Required*
              string

              The IBM Cloud instance ID that identifies your Key Protect service instance.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • Correlation-Id
              string

              The v4 UUID used to correlate and track transactions.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • X-Kms-Key-Ring
              string

              The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

              Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

            Path Parameters

            • id
              Required*
              string

              The v4 UUID or alias that uniquely identifies the key.

              Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/disable   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
            • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err := api.DisableKey(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while disabling the key: ", err)
    return
  }
  fmt.Println("Key successfully disabled")
}

            Response

            Status Code

            • 204

              The key was successfully disabled. No content.

            • 400

              The request is malformed or illegal.

            • 401

              Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

            • 404

              The key could not be found.

            • 409

              The requested key is not in the Active (1) state.

            • 410

              The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using POST /keys/{id}/restore.

            • 429

              Too many requests. Wait a few minutes and try again.

            • 500

              IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

            Example responses
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Key could not be disabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ROOT_REQ_ERR",
          "message": "Requested action can only be completed with a root key.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be disabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be disabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ACTION_INVALID_STATE_ERR",
          "message": "Key is not in a valid state",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key could not be disabled. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Delete references to this key.",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

            Sync associated resources

            Initiate a manual data synchronization request to the associated resources of a key. Regular key lifecycle events automatically notify integrated services of any change. However, in the case a service does not respond to a key lifecycle event notification after four hours, the sync API may be used to initiate a renotification to the integrated services that manage the associated resources linked to the key.

            Note: The services that manage the associated resources linked to the key are responsible for maintaining current records of the key state and version. Key Protect does not have the ability to force data synchronization for other services, which may take up to four hours to complete. The sync API is meant to initiate a request for all associated resources to synchronize their key records with the information returned from the Key Protect API.

            POST /api/v2/keys/{id}/actions/sync

            Authorization

            To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

            • kms.secrets.sync

            Auditing

            Calling this method generates the following auditing event.

            • kms.secrets.sync

            Request

            Custom Headers

            • Bluemix-Instance
              Required*
              string

              The IBM Cloud instance ID that identifies your Key Protect service instance.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • Correlation-Id
              string

              The v4 UUID used to correlate and track transactions.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • X-Kms-Key-Ring
              string

              The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

              Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

            Path Parameters

            • id
              Required*
              string

              The v4 UUID or alias that uniquely identifies the key.

              Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

            • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/actions/sync   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'

            Response

            Status Code

            • 204

              The sync of associate resources for a key has been initiated. No content.

            • 400

              The request is malformed or illegal.

            • 401

              Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

            • 404

              There are two possible causes for HTTP 404 for the synchronization request, the reason code (resources[0].reasons[0].code) as follows: KEY_NOT_FOUND: The specified key could not be found. NOT_SUPPORTED_IN_SATELLITE_LOCATION: The synchronization request for the specified key is not supported in this location.

            • 409

              The key has been synced or updated (i.e. rotated, restored, disabled, enabled, deleted) within the last hour.

            • 429

              Too many requests. Wait a few minutes and try again.

            • 500

              IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

            Example responses
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Associated resources could not be synced. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ROOT_REQ_ERR",
          "message": "Requested action can only be completed with a root key.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Associated resources could not be synced. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND_ERR",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Associated resources could not be synced. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "REQ_TOO_EARLY_ERR",
          "message": "The key was updated recently. Wait and try again.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
            • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

            Set key policies

            Creates or updates one or more policies for the specified key.

            You can set policies for a key, such as an automatic rotation policy or a dual authorization policy to protect against the accidental deletion of keys. Use PUT /keys/{id}/policies to create new policies for a key or update an existing policy.

            PUT /api/v2/keys/{id}/policies

            Authorization

            To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

            • kms.policies.write

            Auditing

            Calling this method generates the following auditing event.

            • kms.policies.write

            Request

            Custom Headers

            • Bluemix-Instance
              Required*
              string

              The IBM Cloud instance ID that identifies your Key Protect service instance.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • Correlation-Id
              string

              The v4 UUID used to correlate and track transactions.

              Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

            • X-Kms-Key-Ring
              string

              The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

              Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

            Path Parameters

            • id
              Required*
              string

              The v4 UUID or alias that uniquely identifies the key.

              Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

            Query Parameters

            • policy
              string

              The type of policy that is associated with the specified key.

              Allowable values: [dualAuthDelete,rotation]

              Possible values: 8 ≤ length ≤ 14

            Request Body

            Required*
            One of

              The base request for key policy create or update.

              Example: 
              {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.policy+json",
      "dualAuthDelete": {
        "enabled": true
      }
    }
  ]
}
              • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/policies   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 2
    },
    "resources": [
      {
        "type": "application/vnd.ibm.kms.policy+json",
        "rotation": {
          "enabled": <true|false>,
          "interval_month": <rotation_interval>
        }
      },
      {
        "type": "application/vnd.ibm.kms.policy+json",
        "dualAuthDelete": {
          "enabled": <true|false>
        }
      }
    ]
  }'
              • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "type": "application/vnd.ibm.kms.policy+json",
        "dualAuthDelete": {
          "enabled": <true|false>
        }
      }
    ]
  }'
              • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/policies?policy=rotation   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "type": "application/vnd.ibm.kms.policy+json",
        "rotation": {
          "enabled": <true|false>,
          "interval_month": <rotation_interval>
        }
      }
    ]
  }'
              • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  // Pass setRotationPolicy as true if setting rotation policy otherwise false
  // Pass setDualAuthDeletePolicy as true if setting dual authorization policy otherwise false
  // Pass dualAuthEnabled as true to enable or false to disable the dual auth delete policy.
  policies, err := api.SetPolicies(context.Background(), <key_ID>, <setRotationPolicy>, <rotation_interval>, <setDualAuthDeletePolicy>, <dualAuthEnabled>)
  if err != nil {
    fmt.Println("Error while setting the policies: ", err)
    return
  }
  b, _ := json.MarshalIndent(policies, "", "  ")
  fmt.Println(string(b))
}
              • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.SetRotationPolicy(context.Background(), <key_ID>, <rotation_interval>)
  if err != nil {
    fmt.Println("Error while setting rotation policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}
              • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  // Pass enabled as true to set the policy and false to unset the policy
  policy, err := api.SetDualAuthDeletePolicy(context.Background(), <key_ID>, <enabled>)
  if err != nil {
    fmt.Println("Error while setting dual auth delete policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}

              Response

              Response Body

              One of

                The base schema for retrieving a dual authorization key policy.

                Status Code

                • 200

                  The policy or policies were successfully created or updated.

                • 204

                  The policy or policies were successfully created or updated. No content.

                • 400

                  The policy or policies cannot be created or updated due to a malformed, invalid, or missing ID.

                • 401

                  Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                • 403

                  Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

                • 410

                  The requested key was previously deleted and is no longer available. Delete references to this key.

                • 422

                  The key with specified ID is invalid for use with policies.

                  A key must be a root key (non-extractable) in the Activated (1) state.

                • 429

                  Too many requests. Wait a few minutes and try again.

                • 500

                  IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                Example responses
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:feddecaf-0000-0000-0000-1234567890ab",
      "rotation": {
        "enabled": true,
        "interval_month": 3
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    },
    {
      "id": "beadcafe-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:beadcafe-0000-0000-0000-1234567890ab",
      "dualAuthDelete": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:feddecaf-0000-0000-0000-1234567890ab",
      "dualAuthDelete": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "beadcafe-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:beadcafe-0000-0000-0000-1234567890ab",
      "rotation": {
        "enabled": true,
        "interval_month": 3
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key."
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key policy could not be created. See `reasons`  for more details.",
      "reasons": [
        {
          "code": "KEY_INVALID_STATE_ERR",
          "message": "Key is not in a valid state",
          "status": 422,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                List key policies

                Retrieves a list of policies that are associated with a specified key.

                You can set policies for a key, such as an automatic rotation policy or a dual authorization policy to protect against the accidental deletion of keys. Use GET /keys/{id}/policies to browse the policies that exist for a specified key.

                GET /api/v2/keys/{id}/policies

                Authorization

                To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                • kms.policies.read

                Auditing

                Calling this method generates the following auditing event.

                • kms.policies.read

                Request

                Custom Headers

                • Bluemix-Instance
                  Required*
                  string

                  The IBM Cloud instance ID that identifies your Key Protect service instance.

                  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                • Correlation-Id
                  string

                  The v4 UUID used to correlate and track transactions.

                  Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                • X-Kms-Key-Ring
                  string

                  The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                  Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                Path Parameters

                • id
                  Required*
                  string

                  The v4 UUID or alias that uniquely identifies the key.

                  Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

                Query Parameters

                • policy
                  string

                  The type of policy that is associated with the specified key.

                  Allowable values: [dualAuthDelete,rotation]

                  Possible values: 8 ≤ length ≤ 14

                • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/policies   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/policies?policy=rotation   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policies, err := api.GetPolicies(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while getting policies: ", err)
    return
  }
  b, _ := json.MarshalIndent(policies, "", "  ")
  fmt.Println(string(b))
}
                • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.GetRotationPolicy(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while getting rotation policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}
                • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.GetDualAuthDeletePolicy(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while getting dual auth delete policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}

                Response

                Response Body

                One of

                  The base schema for retrieving a dual authorization key policy.

                  Status Code

                  • 200

                    The policy resources were successfully retrieved.

                  • 400

                    The request is missing a required field or contains invalid values.

                  • 401

                    Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                  • 403

                    Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

                  • 404

                    The key could not be found.

                  • 429

                    Too many requests. Wait a few minutes and try again.

                  • 500

                    IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                  Example responses
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:feddecaf-0000-0000-0000-1234567890ab",
      "rotation": {
        "enabled": true,
        "interval_month": 3
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    },
    {
      "id": "beadcafe-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:beadcafe-0000-0000-0000-1234567890ab",
      "dualAuthDelete": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:feddecaf-0000-0000-0000-1234567890ab",
      "dualAuthDelete": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "beadcafe-0000-0000-0000-1234567890ab",
      "crn": "crn:v1:bluemix:public:kms:<region>:<account-ID>:<instance-ID>:policy:beadcafe-0000-0000-0000-1234567890ab",
      "rotation": {
        "enabled": true,
        "interval_month": 3
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdateDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist"
    }
  ]
}
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                  • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                  Set instance policies

                  Creates or updates one or more policies for the specified service instance.

                  Note: When you set an instance policy, Key Protect associates the policy information with keys that you add to the instance after the policy is updated. This operation does not affect existing keys in the instance.

                  PUT /api/v2/instance/policies

                  Authorization

                  To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                  • kms.instancepolicies.write

                  Auditing

                  Calling this method generates the following auditing event.

                  • kms.instance-policies.write

                  Request

                  Custom Headers

                  • Bluemix-Instance
                    Required*
                    string

                    The IBM Cloud instance ID that identifies your Key Protect service instance.

                    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                  • Correlation-Id
                    string

                    The v4 UUID used to correlate and track transactions.

                    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                  Query Parameters

                  • policy
                    string

                    The type of policy that is associated with the specified instance.

                    Allowable values: [allowedNetwork,dualAuthDelete,allowedIP,keyCreateImportAccess,metrics,rotation]

                    Possible values: 7 ≤ length ≤ 21

                  Request Body

                  Required*
                  One of

                    The base request for the create or update of instance level policies.

                    Example: 
                    {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "allowedNetwork",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "allowed_network": "private-only"
        }
      }
    }
  ]
}
                    • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 6
    },
    "resources": [
      {
        "policy_type": "allowedNetwork",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "allowed_network": "<public-and-private|private-only>"
          }
        }
      },
      {
        "policy_type": "dualAuthDelete",
        "policy_data": {
          "enabled": <true|false>
        }
      },
      {
        "policy_type": "allowedIP",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "allowed_ip": ["X.X.X.X/N", "X.X.X.X/N"]
          }
        }
      },
      {
        "policy_type": "keyCreateImportAccess",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "create_root_key": <true|false>,
            "create_standard_key": <true|false>,
            "import_root_key": <true|false>,
            "import_standard_key": <true|false>,
            "enforce_token": <true|false>
          }
        }
      },
      {
        "policy_type": "metrics",
        "policy_data": {
          "enabled": <true|false>
        }
      },
      {
        "policy_type": "rotation",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "interval_month": <rotation_interval>
          }
        }
      }
    ]
  }'
                    • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedNetwork   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "policy_type": "allowedNetwork",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "allowed_network": "<public-and-private|private-only>"
          }
        }
      }
    ]
  }'
                    • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "policy_type": "dualAuthDelete",
        "policy_data": {
          "enabled": <true|false>
        }
      }
    ]
  }'
                    • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "policy_type": "metrics",
        "policy_data": {
          "enabled": <true|false>
        }
      }
    ]
  }'
                    • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedIP   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "policy_type": "allowedIP",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "allowed_ip": ["X.X.X.X/N", "X.X.X.X/N"]
          }
        }
      }
    ]
  }'
                    • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "policy_type": "keyCreateImportAccess",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "create_root_key": <true|false>,
            "create_standard_key": <true|false>,
            "import_root_key": <true|false>,
            "import_standard_key": <true|false>,
            "enforce_token": <true|false>
          }
        }
      }
    ]
  }'
                    • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=rotation   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "policy_type": "rotation",
        "policy_data": {
          "enabled": <true|false>,
          "attributes": {
            "interval_month": <rotation_interval>
          }
        }
      }
    ]
  }'
                    • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  // Pass multiple_policies as an object of kp.MultiplePolicies setting
  // the policies accordingly.
  multiple_policies := kp.MultiplePolicies{
    DualAuthDelete: &kp.BasicPolicyData{
      Enabled: <true|false>
    },
    AllowedNetwork: &kp.AllowedNetworkPolicyData{
      Enabled: <true|false>,
      Network: "<public-and-private|private-only>",
    },
    AllowedIP: &kp.AllowedIPPolicyData{
      Enabled: <true|false>,
      IPAddresses: <[]string{<ip_subnet1>,<ip_subnet2>}>
    }
    Metrics: &kp.BasicPolicyData{
      Enabled: <true|false>
    }.
    KeyCreateImportAccess: &kp.KeyCreateImportAccessInstancePolicy{
      Enabled: <true|false>,
      CreateRootKey: <true|false>,
      CreateStandardKey: <true|false>,
      ImportRootKey: <true|false>,
      ImportStandardKey: <true|false>,
      EnforceToken: <true|false>
    }
  }
  err = api.SetPolicies(context.Background(), multiple_policies)
  if err != nil {
    fmt.Println("Error while setting policies: ", err)
    return
  }
  fmt.Println("Instance policies set successfully")
}
                    • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  allowedIPs := []string{<ip_subnet1>,<ip_subnet2>}
  err = api.SetAllowedIPInstancePolicy(context.Background(), <true|false>, allowedIPs)
  if err != nil {
    fmt.Println("Error while setting allowed IP policy: ", err)
    return
  }
  fmt.Println("Allowed IP instance policy set successfully")
}
                    • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  networkType := "<private-only|public-and-private>"
  err = api.SetAllowedNetworkInstancePolicy(context.Background(), <true|false>, networkType)
  if err != nil {
    fmt.Println("Error while setting allowed network policy: ", err)
    return
  }
  fmt.Println("Allowed network instance policy set successfully")
}
                    • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err = api.SetDualAuthInstancePolicy(context.Background(), <true|false>)
  if err != nil {
    fmt.Println("Error while setting dual authorization policy: ", err)
    return
  }
  fmt.Println("Dual auth instance policy set successfully")
}
                    • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  // Pass true to set the policy or false to unset the policy
  attributes := map[string]bool{
    kp.CreateRootKey: <true|false>,
    kp.CreateStandardKey: <true|false>,
    kp.ImportRootKey: <true|false>,
    kp.ImportStandardKey: <true|false>,
    kp.EnforceToken: <true|false>,
  }
  err = api.SetKeyCreateImportAccessInstancePolicy(context.Background(), <true|false>, attributes)
  if err != nil {
    fmt.Println("Error while setting key create import access policy: ", err)
    return
  }
  fmt.Println("Key create import access instance policy set successfully")
}
                    • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err = api.SetMetricsInstancePolicy(context.Background(), <true|false>)
  if err != nil {
    fmt.Println("Error while setting metrics policy: ", err)
    return
  }
  fmt.Println("Metrics instance policy set successfully")
}
                    • package main

import (
  "context"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  intervalMonth := 3
  enable := true

  err := client.SetRotationInstancePolicy(context.Background(), enable, &intervalMonth)
  if err != nil {
    fmt.Println(err)
  }

  rotationInstancePolicy, err := client.GetRotationInstancePolicy(context.Background())
  if err != nil {
    fmt.Println(err)
  }
  fmt.Println(rotationInstancePolicy)
}

                    Response

                    Status Code

                    • 204

                      The policy or policies were successfully created or updated. No content.

                    • 400

                      The policy or policies cannot be created or updated due to a malformed or invalid request.

                    • 401

                      Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                    • 403

                      There are two possible causes for HTTP 403 while trying to set instance policies, specifying a reason code (resouces[0].reasons[0].code) as follows: FEATURE_RESTRICTED_ERR: Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. CONFIG_RULE_CONFLICT_ERR: Instance policy could not be created, requested change is not compliant with configuration rules.

                    • 410

                      The requested key was previously deleted and is no longer available. Delete references to this key.

                    • 429

                      Too many requests. Wait a few minutes and try again.

                    • 500

                      IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                    Example responses
                    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key."
    }
  ]
}
                    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                    List instance policies

                    Retrieves a list of policies that are associated with a specified service instance.

                    You can manage advanced preferences for keys in your service instance by creating instance-level policies. Use GET /instance/policies to browse the policies that are associated with the specified instance. Currently, dual authorization policies are supported.

                    GET /api/v2/instance/policies

                    Authorization

                    To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                    • kms.instancepolicies.read

                    Auditing

                    Calling this method generates the following auditing event.

                    • kms.instance-policies.read

                    Request

                    Custom Headers

                    • Bluemix-Instance
                      Required*
                      string

                      The IBM Cloud instance ID that identifies your Key Protect service instance.

                      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                    • Correlation-Id
                      string

                      The v4 UUID used to correlate and track transactions.

                      Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                    Query Parameters

                    • policy
                      string

                      The type of policy that is associated with the specified instance.

                      Allowable values: [allowedNetwork,dualAuthDelete,allowedIP,keyCreateImportAccess,metrics,rotation]

                      Possible values: 7 ≤ length ≤ 21

                    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedNetwork   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedIP   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                    • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=rotation   -H 'accept: application/vnd.ibm.kms.policy+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policies, err := api.GetInstancePolicies(context.Background())
  if err != nil {
    fmt.Println("Error while getting policies: ", err)
    return
  }
  b, _ := json.MarshalIndent(policies, "", "  ")
  fmt.Println(string(b))
}
                    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.GetAllowedIPInstancePolicy(context.Background())
  if err != nil {
    fmt.Println("Error while getting allowed IP policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}
                    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.GetAllowedNetworkInstancePolicy(context.Background())
  if err != nil {
    fmt.Println("Error while getting allowed network policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}
                    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.GetDualAuthInstancePolicy(context.Background())
  if err != nil {
    fmt.Println("Error while getting dual auth policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}
                    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.GetKeyCreateImportAccessInstancePolicy(context.Background())
  if err != nil {
    fmt.Println("Error while getting key create import access policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}
                    • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  policy, err := api.GetMetricsInstancePolicy(context.Background())
  if err != nil {
    fmt.Println("Error while getting metrics policy: ", err)
    return
  }
  b, _ := json.MarshalIndent(policy, "", "  ")
  fmt.Println(string(b))
}

                    Response

                    Response Body

                    One of

                      Properties that are associated with retrieving an instance level allowed network policy.

                      Status Code

                      • 200

                        The policy resources were successfully retrieved.

                      • 400

                        The request is missing a required field or contains invalid values.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

                      • 404

                        The key could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 6
  },
  "resources": [
    {
      "policy_type": "allowedNetwork",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "allowed_network": "private-only"
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    },
    {
      "policy_type": "dualAuthDelete",
      "policy_data": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    },
    {
      "policy_type": "metrics",
      "policy_data": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    },
    {
      "policy_type": "allowedIP",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "allowed_ip": [
            "X.X.X.X/N",
            "X.X.X.X/N"
          ]
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    },
    {
      "policy_type": "keyCreateImportAccess",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "create_root_key": true,
          "create_standard_key": true,
          "import_root_key": true,
          "import_standard_key": true,
          "enforce_token": false
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    },
    {
      "policy_type": "rotation",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "interval_month": 3
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "allowedNetwork",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "allowed_network": "private-only"
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "dualAuthDelete",
      "policy_data": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "allowedIP",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "allowed_ip": [
            "X.X.X.X/N",
            "X.X.X.X/N"
          ]
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "keyCreateImportAccess",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "create_root_key": true,
          "create_standard_key": true,
          "import_root_key": true,
          "import_standard_key": true,
          "enforce_token": false
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "metrics",
      "policy_data": {
        "enabled": true
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "rotation",
      "policy_data": {
        "enabled": true,
        "attributes": {
          "interval_month": 3
        }
      },
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Retrieve allowed IP port

                      Retrieves the private endpoint port associated with your service instance's active allowed IP policy. If the instance does not contain an active allowed IP policy, no information will be returned.

                      GET /api/v2/instance/allowed_ip_port

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.instance.readallowedipport

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.instance-allowed-ip-port.read

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/instance/allowed_ip_port   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.allowed_ip_port+json'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  port, err := api.GetAllowedIPPrivateNetworkPort(context.Background())
  if err != nil {
    fmt.Println("Error while getting allowed IP private port: ", err)
    return
  }
  fmt.Printf("Port number: %d", port)
}

                      Response

                      Response Body

                      AllowedIPPort

                      Properties associated with the port associated with an instance with an allowed IP policy.

                      Status Code

                      • 200

                        The allowed IP port information was successfully retrieved.

                      • 400

                        The request is missing a required field or contains invalid values.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.allowed_ip_metadata+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "private_endpoint_port": 8888
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Create an import token

                      Creates an import token that you can use to encrypt and import root keys into the service. Learn more.

                      When you call POST /import_token, Key Protect creates an RSA key-pair from its HSMs. The service encrypts and stores the private key in the HSM, and returns the corresponding public key when you call GET /import_token. You can create only one import token per service instance.

                      POST /api/v2/import_token

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.importtoken.create

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.import-token.create

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                        Default: default

                      Request Body

                      ImportToken

                      The base request to create an import token.

                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/import_token   -H 'accept: application/vnd.ibm.collection+json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
    "expiration": "<expiration_time>",
    "maxAllowedRetrievals": <use_count>
  }'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  importToken, err := api.CreateImportToken(context.Background(), <expiration_time>, <use_count>)
  if err != nil {
    fmt.Println("Error while creating import token: ", err)
    return
  }
  b, _ := json.MarshalIndent(importToken, "", "  ")
  fmt.Println(string(b))
}

                      Response

                      Response Body

                      ImportToken

                      Properties that are associated with import tokens.

                      Status Code

                      • 200

                        The import token was successfully created.

                      • 400

                        The import token cannot be created due to a malformed or invalid request.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "creationDate": "2000-03-21T00:00:00Z",
  "expirationDate": "2000-03-21T00:00:00Z",
  "maxAllowedRetrievals": 10,
  "remainingRetrievals": 10
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Retrieve an import token

                      Retrieves the import token that is associated with your service instance.

                      When you call GET /import_token, Key Protect returns the public key that you can use to encrypt and import key material to the service, along with details about the key.

                      Note: After you reach the maxAllowedRetrievals or expirationDate for the import token, the import token and its associated public key can no longer be used for key operations. To create a new import token, use POST /import_token.

                      GET /api/v2/import_token

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.importtoken.read

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.import-token.read

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                        Default: default

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/import_token   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.import_token+json'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  importToken, err := api.GetImportTokenTransportKey(context.Background())
  if err != nil {
    fmt.Println("Error while getting import token: ", err)
    return
  }
  b, _ := json.MarshalIndent(importToken, "", "  ")
  fmt.Println(string(b))
}

                      Response

                      Response Body

                      GetImportToken

                      The base schema for retrieving an import token.

                      Status Code

                      • 200

                        The import token was successfully retrieved.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. Learn more.

                      • 404

                        There are two possible causes for HTTP 404 while trying to retrieve an import token, specifying a reason code (resouces[0].reasons[0].code) as follows: IMPORT_TOKEN_NOT_FOUND_ERR: An import token was not found in the specified service instance. To create an import token, use POST /import_token. INSTANCE_NOT_FOUND_ERR: Import token could not be retrieved, instance does not exist.

                      • 409

                        The import token has reached its maxAllowedRetrievals or expirationDate, and it is no longer available for use. To create a new import token, use POST /import_token.

                        In very rare cases, the import token may expire before its expiration time. Ensure that your client application is configured with a retry mechanism for catching and responding to 409 conflict exceptions.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "creationDate": "2000-03-21T00:00:00Z",
  "expirationDate": "2000-03-21T00:00:00Z",
  "maxAllowedRetrievals": 10,
  "remainingRetrievals": 9,
  "payload": "QUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUE=",
  "nonce": "8zJE9pKVdXVe/nLb"
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not found: An import token was not found in the specified service instance. To create an import token, use 'POST /import_token'."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: The import token has reached its 'maxAllowedRetrievals' or 'expirationDate'. To create a new import token, use 'POST /import_token'."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Create a registration

                      Service to service calls only. Creates a registration between a root key and a cloud resource, such as a Cloud Object Storage bucket. The key is identified by its ID, and the cloud resource is identified by its Cloud Resource Name (CRN).

                      POST /api/v2/keys/{id}/registrations/{urlEncodedResourceCRN}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.registrations.create

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.registrations.create

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID or alias that uniquely identifies the key.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

                      • urlEncodedResourceCRN
                        Required*
                        string

                        The URL encoded Cloud Resource Name (CRN) that uniquely identifies the cloud resource. At minimum, provide a CRN that includes the service-instance segment.

                        Possible values: 9 ≤ length ≤ 400, Value must match regular expression ^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$

                        Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f00000000000000000000000000000000%3afeddecaf-0000-0000-0000-1234567890ab%3a%3abucket

                      Request Body

                      CreateRegistration

                      The base request for creating a registration.

                      Examples: 
                      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration_input+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "preventKeyDeletion": false,
      "description": "A resource registration on a Key Protect key"
    }
  ]
}
                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/registrations/<url_encoded_CRN>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.registration_input+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "preventKeyDeletion": "false",
        "description": "A resource registration on a Key Protect key"
      }
    ]
  }'

                      Response

                      Response Body

                      Registration

                      Properties associated with a registration response.

                      Status Code

                      • 200

                        A registration with identical properties (keyId, resourceCrn, preventKeyDeletion, description, and registrationMetadata) was previously created between the specified key and cloud resource.

                      • 201

                        A new registration was successfully created.

                      • 400

                        The registration could not be created due to a malformed urlEncodedResourceCRN, an invalid or missing request body, or an invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        You are not authorized to make this request due to missing authorization between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.

                      • 404

                        The key with specified ID could not be found.

                      • 409

                        A registration with different properties already exists between the specified key and cloud resource.

                      • 422

                        The key with specified ID is invalid for use with registrations.

                        A key must be a root key (non-extractable) in the Activated (1) state.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<location>:a/<account-id>:<service-instance>:<resource-type>:<resource>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "A resource registration on a Key Protect key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<location>:a/<account-id>:<service-instance>:<resource-type>:<resource>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "A resource registration on a Key Protect key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PARAM_ERR",
          "message": "The param 'urlEncodedResourceCRN' must be: specified to no more than 10 segments",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Caller is not authorized to make this request.",
      "reasons": [
        {
          "code": "RESOURCE_OWNER_ERR",
          "message": "The resource queried does not belong to the service.",
          "status": 403,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "REGISTRATION_DUP_ERR",
          "message": "Registration already exists",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_INVALID_STATE_ERR",
          "message": "Key is not in a valid state",
          "status": 422,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Update a registration

                      Service to service calls only. Updates an existing registration based on the properties that you specify.

                      When you call PATCH /registrations, Key Protect updates only the properties that you specify in the request entity-body. To replace the registration, use PUT /registrations. The preventKeyDeletion policy should only be set if a WORM policy must be satisfied (as would be needed for this example: https://www.ibm.com/docs/en/spectrum-scale/5.0.1?topic=ics-how-write-once-read-many-worm-storage-works). Do not set this policy by default.

                      PATCH /api/v2/keys/{id}/registrations/{urlEncodedResourceCRN}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.registrations.merge

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.registrations.merge

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID or alias that uniquely identifies the key.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

                      • urlEncodedResourceCRN
                        Required*
                        string

                        The URL encoded Cloud Resource Name (CRN) that uniquely identifies the cloud resource. At minimum, provide a CRN that includes the service-instance segment.

                        Possible values: 9 ≤ length ≤ 400, Value must match regular expression ^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$

                        Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f00000000000000000000000000000000%3afeddecaf-0000-0000-0000-1234567890ab%3a%3abucket

                      Request Body

                      Required*
                      UpdateRegistration

                      The base request for updating a registration.

                      Examples: 
                      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration_input+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "preventKeyDeletion": false,
      "description": "A resource registration on a Key Protect key"
    }
  ]
}
                      • curl -X PATCH   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/registrations/<url_encoded_CRN>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.registration_input+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "preventKeyDeletion": "false"
      }
    ]
  }'

                      Response

                      Response Body

                      Registration

                      Properties associated with a registration response.

                      Status Code

                      • 200

                        The registration was successfully updated.

                      • 400

                        The registration could not be updated due to a malformed urlEncodedResourceCRN, an invalid or missing request body, or an invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        You are not authorized to make this request due to missing authorization between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.

                      • 404

                        The registration or key could not be found. Verify that the specified key ID and CRN are valid.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<location>:a/<account-id>:<service-instance>:<resource-type>:<resource>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "A resource registration on a Key Protect key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be updated. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PARAM_ERR",
          "message": "The param 'urlEncodedResourceCRN' must be specified to no more than 10 segments.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Caller is not authorized to make this request.",
      "reasons": [
        {
          "code": "RESOURCE_OWNER_ERR",
          "message": "The resource queried does not belong to the service.",
          "status": 403,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be updated. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "REGISTRATION_NOT_FOUND_ERR",
          "message": "Registration does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Replace a registration

                      Service to service calls only. Replace an existing registration between a root key and a cloud resource. The key is identified by its ID, and the cloud resource is identified by its Cloud Resource Name (CRN).

                      When you call PUT /registrations, Key Protect replaces the existing registration with the properties that you provide in the request entity-body.

                      PUT /api/v2/keys/{id}/registrations/{urlEncodedResourceCRN}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.registrations.write

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.registrations.write

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID or alias that uniquely identifies the key.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

                      • urlEncodedResourceCRN
                        Required*
                        string

                        The URL encoded Cloud Resource Name (CRN) that uniquely identifies the cloud resource. At minimum, provide a CRN that includes the service-instance segment.

                        Possible values: 9 ≤ length ≤ 400, Value must match regular expression ^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$

                        Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f00000000000000000000000000000000%3afeddecaf-0000-0000-0000-1234567890ab%3a%3abucket

                      Request Body

                      Required*
                      ReplaceRegistration

                      The base request for replacing a registration.

                      Examples: 
                      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration_input+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "preventKeyDeletion": false,
      "description": "A resource registration on a Key Protect key",
      "registrationMetadata": "Registration metadata",
      "keyVersionId": "fadedbee-0000-0000-0000-1234567890ab"
    }
  ]
}
                      • curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/registrations/<url_encoded_CRN>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.registration_input+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "preventKeyDeletion": "false",
        "description": "A resource registration on a Key Protect key",
        "keyVersionId": "<key version ID>"
      }
    ]
  }'

                      Response

                      Response Body

                      Registration

                      Properties associated with a registration response.

                      Status Code

                      • 200

                        The registration was successfully replaced.

                      • 400

                        The registration could not be replaced due to a malformed urlEncodedResourceCRN, an invalid or missing request body, or an invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        You are not authorized to make this request due to missing authorization between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.

                      • 404

                        The registration or key could not be found. Verify that the specified key ID and CRN are valid.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<location>:a/<account-id>:<service-instance>:<resource-type>:<resource>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "A resource registration on a Key Protect key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be replaced. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PARAM_ERR",
          "message": "The param 'urlEncodedResourceCRN' must be specified to no more than 10 segments.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Caller is not authorized to make this request.",
      "reasons": [
        {
          "code": "RESOURCE_OWNER_ERR",
          "message": "The resource queried does not belong to the service.",
          "status": 403,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be replaced. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "REGISTRATION_NOT_FOUND_ERR",
          "message": "Registration does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Delete a registration

                      Service to service calls only. Deletes an existing registration between a root key and a cloud resource.

                      This action permanently removes the registration from the Key Protect database.

                      DELETE /api/v2/keys/{id}/registrations/{urlEncodedResourceCRN}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.registrations.delete

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.registrations.delete

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      • Prefer
                        string

                        Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

                        Allowable values: [return=representation,return=minimal]

                        Possible values: 14 ≤ length ≤ 21

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID or alias that uniquely identifies the key.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

                      • urlEncodedResourceCRN
                        Required*
                        string

                        The URL encoded Cloud Resource Name (CRN) that uniquely identifies the cloud resource. At minimum, provide a CRN that includes the service-instance segment.

                        Possible values: 9 ≤ length ≤ 400, Value must match regular expression ^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$

                        Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f00000000000000000000000000000000%3afeddecaf-0000-0000-0000-1234567890ab%3a%3abucket

                      • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/registrations/<url_encoded_CRN>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'

                      Response

                      Response Body

                      Registration

                      Properties associated with a registration response.

                      Status Code

                      • 200

                        The registration was successfully deleted.

                      • 204

                        The registration was successfully deleted. No content.

                      • 400

                        The registration could not be deleted due to a malformed urlEncodedResourceCRN, an invalid or missing request body, or an invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        You are not authorized to make this request due to missing authorization between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.

                      • 404

                        The registration or key could not be found. Verify that the specified key ID and CRN are valid.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<location>:a/<account-id>:<service-instance>:<resource-type>:<resource>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00.000Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00.000Z",
      "description": "A resource registration on a Key Protect key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "fadedbee-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00.000Z"
      }
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PARAM_ERR",
          "message": "The param 'urlEncodedResourceCRN' must be: specified to no more than 10 segments",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Caller is not authorized to make this request.",
      "reasons": [
        {
          "code": "RESOURCE_OWNER_ERR",
          "message": "The resource queried does not belong to the service.",
          "status": 403,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "REGISTRATION_NOT_FOUND_ERR",
          "message": "Registration does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Deactivate a registration

                      Deprecated. Invokes an action, such as a deactivate operation, on a registration with the specified key ID and CRN.

                      When a customer deletes a root key that is associated with a cloud resource, the registration between the resources moves to the Suspended state. As an integrated service, use POST /keys/{id}/registrations?action=deactivate to acknowledge the deletion. This action moves the registration to a Deactivated state.

                      POST /api/v2/keys/{id}/registrations

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      • Prefer
                        string

                        Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier as metadata. A header containing return=representation returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material. Note: During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent GET /keys/{id} request.

                        Allowable values: [return=representation,return=minimal]

                        Possible values: 14 ≤ length ≤ 21

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID that uniquely identifies the key.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Query Parameters

                      • action
                        Required*
                        string

                        The action to perform on the specified key.

                        Allowable values: [deactivate]

                        Possible values: length = 10

                      Request Body

                      Required*
                      DeactivateRegistration

                      The base request for registration actions.

                      Examples: 
                      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.resource_crn+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<location>:a/<account-id>:<service-instance>:<resource-type>:<resource>"
    }
  ]
}
                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/registrations?action=deactivate   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.crn+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "resourceCrn": "<CRN that is associated with the specified deleted key ID to deactivate>"
      }
    ]
  }'

                      Response

                      Response Body

                      DeactivateRegistration

                      The base schema for the request body of deactivate registration.

                      Status Code

                      • 200

                        The requested action was successfully performed on the registration.

                      • 204

                        The requested action was successfully performed on the registration. No content.

                      • 400

                        The requested action could not be performed due to an invalid or missing request body, or invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        You are not authorized to make this request due to missing authorization between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.

                      • 404

                        The registration or key could not be found. Verify that the specified key ID and CRN are valid.

                      • 409

                        The action could not be performed on the registration because it is in an invalid state.

                        For action deactivate, the registration must be in the Suspended (2) state.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.resource_crn+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "resourceCrn": "crn:v1:bluemix:public:<service-name>:<location>:a/<account-id>:<service-instance>:<resource-type>:<resource>"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Action could not be performed on registration. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field 'resourceCrn' must be:",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "urlEncodedResourceCRNQuery"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Caller is not authorized to make this request.",
      "reasons": [
        {
          "code": "RESOURCE_OWNER_ERR",
          "message": "The resource queried does not belong to the service.",
          "status": 403,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Action could not be performed on registration. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "REGISTRATION_NOT_FOUND_ERR",
          "message": "Registration does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Action could not be performed on registration. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "REG_INVALID_STATE_ERR",
          "message": "Request action cannot be performed on the registration in its current state.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      List registrations for a key

                      Retrieves a list of registrations that are associated with a specified root key.

                      When you use a root key to protect an IBM Cloud resource, such as a Cloud Object Storage bucket, Key Protect creates a registration between the resource and root key. You can use GET /keys/{id}/registrations to understand which cloud resources are protected by the key that you specify.

                      GET /api/v2/keys/{id}/registrations

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.registrations.list

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.registrations.list

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID that uniquely identifies the key.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Query Parameters

                      • limit
                        integer

                        The number of registrations to retrieve. By default returns the first 200 registrations. To retrieve a different set of registrations, use limit with offset to page through your available resources. The maximum value for limit is 5,000. Usage: If you have 20 registrations that are associated with a key, and you want to retrieve only the first 5 registrations, use ../registrations?limit=5.

                        Possible values: 1 ≤ value ≤ 5000

                        Default: 200

                      • offset
                        integer

                        The number of registrations to skip. By specifying offset, you retrieve a subset of registrations that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have 100 registrations that are associated with a key, and you want to retrieve registrations 26 through 50, use ../registrations?offset=25&limit=25.

                        Possible values: value ≥ 0

                        Default: 0

                      • urlEncodedResourceCRNQuery
                        string

                        Filters for resources that are associated with a specified Cloud Resource Name (CRN) by using URL encoded wildcard characters (*). The parameter should contain all CRN segments and must be URL encoded. Supports a prefix search when you specify * on the last CRN segment. Usage: To list registrations that are associated with all resources in <service-instance>, use a URL encoded version of the following string: crn:v1:bluemix:public:<service-name>:<location>:a/<account>:<service-instance>:*:*. To search for subresources, use the following CRN format: crn:v1:bluemix:public:<service-name>:<location>:a/<account>:<service-instance>:<resource-type>:<resource>/<subresource>. For more examples, see CRN query examples.

                        Possible values: 9 ≤ length ≤ 4000, Value must match regular expression ^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$

                        Example: crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F00000000000000000000000000000000%3Afeddecaf-0000-0000-0000-1234567890ab%3A*%3A*

                      • preventKeyDeletion
                        boolean

                        Filters registrations based on the preventKeyDeletion property. You can use this query parameter to search for registered cloud resources that are non-erasable due to a retention policy. This policy should only be set if a WORM policy (https://www.ibm.com/docs/en/spectrum-scale/5.0.1?topic=ics-how-write-once-read-many-worm-storage-works) must be satisfied. Do not set this policy by default. Usage: To search for registered cloud resources that have a retention policy, use ../registrations?preventKeyDeletion=true.

                      • totalCount
                        boolean

                        If set to true, returns totalCount in the response metadata for use with pagination. The totalCount value returned specifies the total number of registrations that match the request, disregarding limit and offset. Usage: To return the totalCount value for use with pagination, use ../registrations?totalCount=true.

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/registrations   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  registrations, err := api.ListRegistrations(context.Background(), <keyID>, "")
  if err != nil {
    fmt.Println("Error while getting registrations: ", err)
    return
  }
  b, _ := json.MarshalIndent(registrations, "", "  ")
  fmt.Println(string(b))
}

                      Response

                      Response Body

                      RegistrationWithTotalCount

                      Properties associated with a list registration response which may include total registration count.

                      Status Code

                      • 200

                        The list of registrations was successfully retrieved.

                      • 400

                        The list of registrations could not be retrieved due to a malformed urlEncodedResourceCRN, an invalid or missing request body, or an invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        You are not authorized to make this request due to missing authorization between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.

                      • 404

                        The key with specified ID could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 2,
    "totalCount": 4
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "Registration between a bucket and root key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "addedace-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    },
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<other-bucket-name>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "Registration between the root key and a different bucket",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "addedace-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PARAM_ERR",
          "message": "The param 'urlEncodedResourceCRNQuery' must be: specified to at least the service instance.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "urlEncodedResourceCRNQuery"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Caller is not authorized to make this request.",
      "reasons": [
        {
          "code": "RESOURCE_OWNER_ERR",
          "message": "The resource queried does not belong to the service.",
          "status": 403,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND",
          "message": "Key does not exist.",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      List registrations for any key

                      Retrieves a list of registrations that match the Cloud Resource Name (CRN) query that you specify.

                      When you use a root key to protect an IBM Cloud resource, such as a Cloud Object Storage bucket, Key Protect creates a registration between the resource and root key. You can use GET /keys/registrations to understand which cloud resources are protected by keys in your Key Protect service instance.

                      GET /api/v2/keys/registrations

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.registrations.list

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.registrations.list

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Query Parameters

                      • urlEncodedResourceCRNQuery
                        string

                        Filters for resources that are associated with a specified Cloud Resource Name (CRN) by using URL encoded wildcard characters (*). The parameter should contain all CRN segments and must be URL encoded. If provided, the parameter should not contain (*) in the first eight segments. If this parameter is not provided, registrations for all keys in the requested Key Protect instance are returned.

                        Possible values: 9 ≤ length ≤ 4000, Value must match regular expression ^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$

                        Example: crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F00000000000000000000000000000000%3Afeddecaf-0000-0000-0000-1234567890ab%3A*%3A*

                      • limit
                        integer

                        The number of registrations to retrieve. By default returns the first 200 registrations. To retrieve a different set of registrations, use limit with offset to page through your available resources. The maximum value for limit is 5,000. Usage: If you have 20 registrations that are associated with a key, and you want to retrieve only the first 5 registrations, use ../registrations?limit=5.

                        Possible values: 1 ≤ value ≤ 5000

                        Default: 200

                      • offset
                        integer

                        The number of registrations to skip. By specifying offset, you retrieve a subset of registrations that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have 100 registrations that are associated with a key, and you want to retrieve registrations 26 through 50, use ../registrations?offset=25&limit=25.

                        Possible values: value ≥ 0

                        Default: 0

                      • preventKeyDeletion
                        boolean

                        Filters registrations based on the preventKeyDeletion property. You can use this query parameter to search for registered cloud resources that are non-erasable due to a retention policy. This policy should only be set if a WORM policy (https://www.ibm.com/docs/en/spectrum-scale/5.0.1?topic=ics-how-write-once-read-many-worm-storage-works) must be satisfied. Do not set this policy by default. Usage: To search for registered cloud resources that have a retention policy, use ../registrations?preventKeyDeletion=true.

                      • totalCount
                        boolean

                        If set to true, returns totalCount in the response metadata for use with pagination. The totalCount value returned specifies the total number of registrations that match the request, disregarding limit and offset. Usage: To return the totalCount value for use with pagination, use ../registrations?totalCount=true.

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/registrations?urlEncodedResourceCRNQuery=<url_encoded_resource_CRN_query>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  registrations, err := api.ListRegistrations(context.Background(), "", <crn>)
  if err != nil {
    fmt.Println("Error while getting registrations: ", err)
    return
  }
  b, _ := json.MarshalIndent(registrations, "", "  ")
  fmt.Println(string(b))
}

                      Response

                      Response Body

                      RegistrationWithTotalCount

                      Properties associated with a list registration response which may include total registration count.

                      Status Code

                      • 200

                        The list of registrations was successfully retrieved.

                      • 400

                        The list of registrations could not be retrieved due to a malformed urlEncodedResourceCRNQuery, an invalid or missing request body, or a mismatch between the cloud service CRN and the resource CRN.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 403

                        You are not authorized to make this request due to missing authorization between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 2,
    "totalCount": 4
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "Registration between a bucket and root key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "addedace-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    },
    {
      "keyId": "beadcafe-0000-0000-0000-1234567890ab",
      "keyName": "Root-key",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<other-bucket-name>",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z",
      "updatedBy": "IBMid-0000000000",
      "lastUpdated": "2000-03-21T00:00:00Z",
      "description": "Registration between a bucket and root key",
      "preventKeyDeletion": false,
      "keyVersion": {
        "id": "beadcafe-0000-0000-0000-1234567890ab",
        "creationDate": "2000-03-21T00:00:00Z"
      }
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PARAM_ERR",
          "message": "The param 'urlEncodedResourceCRNQuery' must be: specified to at least the service instance.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "urlEncodedResourceCRNQuery"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Caller is not authorized to make this request.",
      "reasons": [
        {
          "code": "RESOURCE_OWNER_ERR",
          "message": "The resource queried does not belong to the service.",
          "status": 403,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Acknowledge key events

                      Service to service calls only. Acknowledges a key lifecycle event.

                      When a customer performs an action on a root key, Key Protect uses Hyperwarp to notify the cloud services that are registered with the key. To acknowledge the Hyperwarp event, registered services must call POST /api/v2/event_ack.

                      POST /api/v2/event_ack

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.secrets.eventack

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.secrets-event.ack

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                        Default: default

                      Request Body

                      Required*
                      application/vnd.ibm.kms.event_acknowledge+jsonEventAcknowledge

                      The base request for acknowledging a key action events.

                      Examples: 
                      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.event_acknowledge+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "eventId": "feddecaf-0000-0000-0000-1234567890ab",
      "adopterKeyState": "DEK_ENABLED",
      "timestamp": "2000-03-21T00:00:00Z",
      "keyStateData": {
        "keyVersion": "fadedbee-0000-0000-0000-1234567890ab"
      }
    }
  ]
}
                      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.event_acknowledge+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "eventId": "feddecaf-0000-0000-0000-1234567890ab",
      "adopterKeyState": "DEK_ENABLED",
      "timestamp": "2000-03-21T00:00:00Z",
      "keyStateData": {
        "keyVersion": "fadedbee-0000-0000-0000-1234567890ab"
      }
    },
    {
      "eventId": "addedace-0000-0000-0000-1234567890ab",
      "adopterKeyState": "DEK_ENABLED",
      "timestamp": "2000-03-21T00:00:00Z"
    },
    {
      "eventId": "beadcafe-0000-0000-0000-1234567890ab",
      "adopterKeyState": "DEK_DISABLED",
      "timestamp": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/event_ack   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.event_acknowledge+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "eventId": "<event_ID>",
        "adopterKeyState": "DEK_ENABLED",
        "timestamp": "2000-03-21T00:00:00Z",
        "keyStateData": {
          "keyVersion": "<key_version>"
        }
      }
    ]
  }'

                      Response

                      Status Code

                      • 204

                        The acknowledgement for the list of key events was performed successfully. No content.

                      • 400

                        The event acknowledgement could not be performed due to an invalid or missing request body.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        There are two possible causes for HTTP 404 for the event acknowledgement request, the reason code (resources[0].reasons[0].code) as follows: KEY_NOT_FOUND: The key for the specified event could not be found. NOT_SUPPORTED_IN_SATELLITE_LOCATION: The event acknowledgement is not supported in this location.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Event acknowledgement could not be performed for this service. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "MISSING_FIELD_ERR",
          "message": "The field 'timestamp' must be: a valid RFC3339 timestamp",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "timestamp"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Event acknowledgement could not be performed for this service. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "EVENT_NOT_FOUND",
          "message": "Event does not exist",
          "status": 404,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests. Wait a few minutes and try again."
    }
  ]
}

                      Create an alias

                      Creates a unique alias for the specified key.

                      POST /api/v2/keys/{id}/aliases/{alias}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.secrets.createalias

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.secrets-alias.create

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID or alias that uniquely identifies the key.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

                      • alias
                        Required*
                        string

                        A human-readable alias that uniquely identifies a key. Each alias is unique only within the given instance and is not reserved across the Key Protect service. Each key can have up to five aliases. There is no limit to the number of aliases per instance. The length of the alias can be between 2 - 90 characters, inclusive. An alias must be alphanumeric and cannot contain spaces or special characters other than '-' or '_'. Also, the alias cannot be a version 4 UUID and must not be a Key Protect reserved name: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9_-]*$

                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/aliases/<alias>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  keyAlias, err := api.CreateKeyAlias(context.Background(), <alias_name>, <keyID_or_alias>)
  if err != nil {
    fmt.Println("Error while creating key alias name: ", err)
    return
  }
  b, _ := json.MarshalIndent(keyAlias, "", "  ")
  fmt.Println(string(b))
}
                      • public static List<KeyAliasResource> createKeyAlias(String keyId_or_alias, String keyAlias) {
  List<KeyAliasResource> responseObj = null;
  
  try {
    // Construct an instance of the CreateKeyAliasOptions model
    CreateKeyAliasOptions createKeyAliasOptionsModel = new CreateKeyAliasOptions.Builder()
    .id(keyId_or_alias)
    .alias(keyAlias)
    .bluemixInstance("<instance_id>")
    .build();

    // Invoke operation with valid options model
    Response<KeyAlias> response = testClient.createKeyAlias(createKeyAliasOptionsModel).execute();
    responseObj = response.getResult().getResources();
  } catch (ClassCastException e) {
    System.out.println("Error: " + e.toString());
    return responseObj; // null if error
  }
  return responseObj; // key alias resource
}

                      Response

                      Response Body

                      KeyAlias

                      Properties associated with a specific key alias.

                      Status Code

                      • 200

                        An identical alias was previously created for the specified key.

                      • 201

                        A new alias was successfully created.

                      • 400

                        The alias could not be created due to a malformed alias or an invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        There are two possible causes for HTTP 404 while trying to create an alias, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key with specified ID could not be found. INSTANCE_NOT_FOUND_ERR: Key alias could not be created, instance does not exist.

                      • 409

                        There are three possible causes for HTTP 409 while trying to create an alias, specifying a reason code (resouces[0].reasons[0].code) as follows:

                        KEY_ALIAS_QUOTA_ERR: The alias quota for this key or instance has been reached and alias can not be created.

                        KEY_RING_RESOURCE_QUOTA_ERR: Key alias could not be created, the resource quota for key rings in this instance has been reached and alais can not be created.

                        KEY_ALIAS_NOT_UNIQUE_ERR: The alias is already associated with a key in the specified instance.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.alias+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "alias": "my-alias",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.alias+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "fadedbee-0000-0000-0000-1234567890ab",
      "alias": "my-alias",
      "createdBy": "IBMid-0000000000",
      "creationDate": "2000-03-21T00:00:00Z"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param 'alias' must be: alphanumeric, and no spaces or special characters other than '-' or '_', and can not be a version 4 UUID.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "aliases"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_NOT_FOUND",
          "message": "Key does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key alias could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KEY_ALIAS_NOT_UNIQUE_ERR",
          "message": "One or more aliases are already associated with a key in the instance.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Delete an alias

                      Deletes an alias from the associated key.

                      Delete alias does not delete the key.

                      DELETE /api/v2/keys/{id}/aliases/{alias}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.secrets.deletealias

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.secrets-alias.delete

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • X-Kms-Key-Ring
                        string

                        The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an X-Kms-Key-Ring header is: default.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Path Parameters

                      • id
                        Required*
                        string

                        The v4 UUID or alias that uniquely identifies the key.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9-_]{2,90}$

                      • alias
                        Required*
                        string

                        A human-readable alias that uniquely identifies a key. Each alias is unique only within the given instance and is not reserved across the Key Protect service. Each key can have up to five aliases. There is no limit to the number of aliases per instance. The length of the alias can be between 2 - 90 characters, inclusive. An alias must be alphanumeric and cannot contain spaces or special characters other than '-' or '_'. Also, the alias cannot be a version 4 UUID and must not be a Key Protect reserved name: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions.

                        Possible values: 2 ≤ length ≤ 90, Value must match regular expression ^[a-zA-Z0-9_-]*$

                      • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/aliases/<alias>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err := api.DeleteKeyAlias(context.Background(), <alias_name>, <keyID_or_alias>)
  if err != nil {
    fmt.Println("Error while deleting key alias name: ", err)
    return
  }
  fmt.Println("Key alias successfully deleted")
}
                      • public static String deleteKeyAlias (String keyId_or_alias, String keyAlias) {

  // Construct an instance of the DeleteKeyAliasOptions model
  DeleteKeyAliasOptions deleteKeyAliasOptionsModel = new DeleteKeyAliasOptions.Builder()
    .id(keyId_or_alias)
    .alias(keyAlias)
    .bluemixInstance("<instance_id>")
    .build();

  // Invoke operation with valid options model
  try {
    return testClient.deleteKeyAlias(deleteKeyAliasOptionsModel).execute().toString() + " success";
  } catch (ClassCastException e){
    return e.toString();
  }
}

                      Response

                      Status Code

                      • 204

                        An alias was successfully deleted. No content.

                      • 400

                        The alias could not be deleted due to a malformed alias or an invalid key ID.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        There are two possible causes for HTTP 404 while trying to delete an alias, specifying a reason code (resouces[0].reasons[0].code) as follows: ALIAS_NOT_FOUND_ERR: The alias with specified key ID could not be found. INSTANCE_NOT_FOUND_ERR: Key alias could not be deleted, instance does not exist.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be deleted. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The param 'alias' must be: alphanumeric, and no spaces or special characters other than '-' or '_', and can not be a version 4 UUID.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "aliases"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be deleted. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "ALIAS_NOT_FOUND",
          "message": "Alias does not exist",
          "status": 404,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      List key rings

                      List all key rings in the instance.

                      GET /api/v2/key_rings

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.keyrings.list

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.key-rings.list

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Query Parameters

                      • limit
                        integer

                        The number of key rings to retrieve. By default, GET /key_rings returns 100 key rings including the default key ring. To retrieve a different set of key rings, use limit with offset to page through your available resources. The maximum value for limit is 5,000. Usage: If you have 20 key rings in your instance, and you want to retrieve only the first 5 key rings, use ../key_rings?limit=5.

                        Possible values: value ≥ 0

                        Default: 100

                      • offset
                        integer

                        The number of key rings to skip. By specifying offset, you retrieve a subset of key rings that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have 20 key rings in your instance, and you want to retrieve keys 10 through 20, use ../keys?offset=10&limit=10.

                        Possible values: value ≥ 0

                        Default: 0

                      • totalCount
                        boolean

                        If set to true, returns totalCount in the response metadata for use with pagination. The totalCount value returned specifies the total number of key rings that match the request, disregarding limit and offset. The default is set to false. Usage: To return the totalCount value for use with pagination, use ../key_rings?totalCount=true.

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/key_rings   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  keyRings, err := api.GetKeyRings(context.Background())
  if err != nil {
    fmt.Println("Error while getting key rings: ", err)
    return
  }
  b, _ := json.MarshalIndent(keyRings, "", "  ")
  fmt.Println(string(b))
}
                      • public static ListKeyRingsWithTotalCount getKeyRings () {
  ListKeyRingsWithTotalCount result = null;

  // Construct an instance of the ListKeyRingsWithTotalCountOptions model
  ListKeyRingsWithTotalCountOptions listKeyRingsWithTotalCountOptionsModel = new ListKeyRingsWithTotalCountOptions.Builder()
    .bluemixInstance("<instance_id>")
    .build();

  try {
    // Invoke operation with valid options model
    Response<ListKeyRingsWithTotalCount> response = testClient.listKeyRingsWithTotalCount(listKeyRingsWithTotalCountOptionsModel).execute();
    return response.getResult();
  } catch (ClassCastException e) {
    return result;
  }
}

                      Response

                      Response Body

                      ListKeyRingsWithTotalCount

                      The base schema for listing key rings.

                      Status Code

                      • 200

                        The list of key rings was successfully retrieved.

                      • 400

                        The request is missing a required field.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key_ring+json",
    "collectionTotal": 3,
    "totalCount": 4
  },
  "resources": [
    {
      "id": "default"
    },
    {
      "id": "example-key-ring",
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000"
    },
    {
      "id": "key-ring-name-2",
      "creationDate": "2000-03-21T00:00:00Z",
      "createdBy": "IBMid-0000000000"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The request is missing a required field."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Create a key ring

                      Create a key ring in the instance with the specified name. The key ring ID default is a reserved key ring ID and cannot be created nor destroyed. The default key ring is an initial key ring that is generated with each newly created instance. All keys not associated with an otherwise specified key ring exist within the default key ring.

                      POST /api/v2/key_rings/{key-ring-id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.keyrings.create

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.key-rings.create

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • key-ring-id
                        Required*
                        string

                        The ID that identifies the key ring. Each ID is unique only within the given instance and is not reserved across the Key Protect service.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/key_rings/<key_ring_id>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err := api.CreateKeyRing(context.Background(), <id>)
  if err != nil {
    fmt.Println("Error while creating key ring: ", err)
    return
  }
  fmt.Println("Key ring successfully created")
}
                      • public static KeyRing createKeyRing (String keyRingId) {
  KeyRing result = null;

  // Construct an instance of the CreateKeyRingOptions model
  CreateKeyRingOptions createKeyRingOptionsModel = new CreateKeyRingOptions.Builder()
    .keyRingId(keyRingId)
    .bluemixInstance("<instance_id>")
    .build();

  try {
    // Invoke operation with valid options model
    Response<KeyRing> response = testClient.createKeyRing(createKeyRingOptionsModel).execute();
    System.out.println("Prelim: " + response.toString());
    result = response.getResult();
    return result;
  } catch (ClassCastException e) {
    return result;
  }
}

                      Response

                      Status Code

                      • 201

                        The key ring was successfully created.

                      • 204

                        The key ring already exists. No content.

                      • 400

                        The key ring could not be created due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 409

                        Key ring resource quota has been reached.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a string matching pattern `^[a-zA-Z0-9-]*$`.",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "key-ring-id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. See `reasons` for more details.",
      "reasons": [
        {
          "code": "KEY_RING_RESOURCE_QUOTA_ERR",
          "message": "The resource quota for key rings in this instance has been reached/exceeded and key rings cannot be created.",
          "status": 409,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Delete key ring

                      Delete the key ring from the instance. The key ring ID default cannot be destroyed.

                      DELETE /api/v2/key_rings/{key-ring-id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.keyrings.delete

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.key-rings.delete

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • key-ring-id
                        Required*
                        string

                        The ID that identifies the key ring. Each ID is unique only within the given instance and is not reserved across the Key Protect service.

                        Possible values: 2 ≤ length ≤ 100, Value must match regular expression ^[a-zA-Z0-9-]*$

                      Query Parameters

                      • force
                        boolean

                        Force delete the key ring. All keys in the key ring are required to be deleted (in state 5) before this action can be performed. If the key ring to be deleted contains keys, they will be moved to the default key ring which requires the kms.secrets.patch IAM action.

                        Default: false

                      • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/key_rings/<key_ring_id>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'
                      • package main

import (
  "context"
  "encoding/json"
  "fmt"

  kp "github.com/IBM/keyprotect-go-client"
)

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err := api.DeleteKeyRing(context.Background())
  if err != nil {
    fmt.Println("Error while deleting key ring: ", err)
    return
  }
  fmt.Println("Key ring successfully deleted")
}
                      • public static String deleteKeyRing (String keyRingId) {

  // Construct an instance of the DeleteKeyRingOptions model
  DeleteKeyRingOptions deleteKeyRingOptionsModel = new DeleteKeyRingOptions.Builder()
    .keyRingId(keyRingId)
    .bluemixInstance("<instance_id>")
    .build();

  try {
    // Invoke operation with valid options model
    return testClient.deleteKeyRing(deleteKeyRingOptionsModel).execute().toString() + " success";
  } catch (ClassCastException e) {
    return e.toString();
  }
}

                      Response

                      Status Code

                      • 204

                        The key ring was successfully deleted. No content.

                      • 400

                        The key ring could not be deleted due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 409

                        There are two possible causes for HTTP 409 while trying to delete a key ring, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_RING_NOT_EMPTY_ERR: The specified key ring contains at least one key (in any state). KEY_RING_KEYS_NOT_DELETED_ERR: (If force is set to true) The specified key ring contains at least one non-deleted key.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a string matching pattern `^[a-zA-Z0-9-]*$`.",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "key-ring-id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. See `reasons` for more details.",
      "reasons": [
        {
          "code": "KEY_RING_NOT_EMPTY_ERR",
          "message": "The specified key ring contains at least one key (in any state).",
          "status": 409,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      List KMIP Adapters

                      Retrieves a list of KMIP Adapters.

                      GET /api/v2/kmip_adapters

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.list

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.list

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Query Parameters

                      • limit
                        integer

                        The number of KMIP Adapters to retrieve. By default, GET /kmip_adapters returns the first 100 KMIP Adapters. To retrieve a different set of KMIP adapters, use limit with offset to page through your available resources. The maximum value for limit is 200. Usage: If you have 20 KMIP Adapters, and you want to retrieve only the first 5 adapters, use ../kmip_adapters?limit=5.

                        Possible values: 1 ≤ value ≤ 200

                        Default: 100

                      • offset
                        integer

                        The number of KMIP adapters to skip. By specifying offset, you retrieve a subset of KMIP adapters that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have 20 KMIP Adapters, and you want to retrieve adapters 11 through 15, use ../kmip_adapters?offset=10&limit=5.

                        Possible values: value ≥ 0

                        Default: 0

                      • totalCount
                        boolean

                        If set to true, returns totalCount in the response metadata for use with pagination. The totalCount value returned specifies the total number of kmip adapters that match the request, disregarding limit and offset. The default is set to false. Usage: To return the totalCount value for use with pagination, use ../kmip_adapters?totalCount=true.

                      • crk_id
                        UUID

                        The root key ID(crk_id) in the profile_data to filter on. This field is currently only applicable to profile "native_1.0". It will only return adapters with profile_data that contains this field. Example usage ../kmip_adapters?crk_id=feddecaf-0000-0000-0000-1234567890ab.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                        Example: feddecaf-0000-0000-0000-1234567890ab

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'

                      Response

                      Response Body

                      ListKMIPAdaptersWithTotalCount

                      The base schema for listing kmip adapter with total count.

                      Status Code

                      • 200

                        Returns a list of all KMIP Adapters.

                      • 400

                        The request is missing a required field.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_adapter+json",
    "collectionTotal": 1,
    "totalCount": 3
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "profile": "native_1.0",
      "profile_data": {
        "crk_id": "beddecaf-0000-0000-0000-1234567890ab"
      },
      "name": "kmip-adapter-123",
      "description": "our 123rd kmip adapter",
      "created_at": "2023-01-23T04:56:07.000Z",
      "created_by": "IBMid-0000000000",
      "updated_at": "2023-01-23T04:56:07.000Z",
      "updated_by": "IBMid-0000000000"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The request is missing a required field."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Create a KMIP Adapter

                      Creates a KMIP adapter.

                      POST /api/v2/kmip_adapters

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.create

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.create

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Query Parameters

                      • allowExpiringKey
                        boolean

                        If set to 'true', allows an active root key containing an expiration date to be associated with the KMIP adapter.

                      Request Body

                      Required*
                      CreateKMIPAdapterRequestBody

                      The base schema for the request body of a POST /kmip_adapters.

                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
      "metadata": {
          "collectionTotal": 1,
          "collectionType": "application/vnd.ibm.kms.kmip_adapter+json"
      },
      "resources": [
          {
              "name": "<name>",
              "profile": "<profile>",
              "profile_data": {
                  "crk_id": "<crk_id>"
              }
          }
      ]
  }'

                      Response

                      Response Body

                      ListKMIPAdapters

                      The base schema for listing kmip adapter(s).

                      Status Code

                      • 201

                        Returns the KMIP Adapter just created.

                      • 400

                        The KMIP Adapter could not be created due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 409

                        KMIP adapter could not be created due to a constraint.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_adapter+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "profile": "native_1.0",
      "profile_data": {
        "crk_id": "beddecaf-0000-0000-0000-1234567890ab"
      },
      "name": "kmip-adapter-123",
      "description": "our 123rd kmip adapter",
      "created_at": "2023-01-23T04:56:07.000Z",
      "created_by": "IBMid-0000000000",
      "updated_at": "2023-01-23T04:56:07.000Z",
      "updated_by": "IBMid-0000000000"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: KMIP Adapter could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field '<name|description>' has an invalid format. Please refer to https://cloud.ibm.com/apidocs/key-protect.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "<name|description>"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: KMIP Adapter could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field `profile` must be one of the following: [`native_1.0`]",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "profile"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: KMIP Adapter could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field '<profile_data.crk_id>' could not be found in the provided kms instance.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "<profile_data.crk_id>"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "KMIP Adapter could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_DUPLICATE_NAME_ERR",
          "message": "There is a kmip adapter in this kms instance with the same name. Please choose a different name.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "KMIP Adapter could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "NATIVE_CRK_ID_NOT_FOUND_ERR",
          "message": "Root key in native profile body does not exist in the kms instance",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "KMIP Adapter could not be created. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "NATIVE_INVALID_CRK_ERR",
          "message": "Key id in native profile body is either not a root key or is not in active state",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Retrieve a KMIP Adapter

                      Retrieves a KMIP adapter using its id / name.

                      GET /api/v2/kmip_adapters/{id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.read

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.read

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Response Body

                      ListKMIPAdapters

                      The base schema for listing kmip adapter(s).

                      Status Code

                      • 200

                        Returns the KMIP Adapter with the given ID / name.

                      • 400

                        The KMIP Adapter could not be retrieved due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        The kmip adapter with that id / name could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_adapter+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "profile": "native_1.0",
      "profile_data": {
        "crk_id": "beddecaf-0000-0000-0000-1234567890ab"
      },
      "name": "kmip-adapter-123",
      "description": "our 123rd kmip adapter",
      "created_at": "2023-01-23T04:56:07.000Z",
      "created_by": "IBMid-0000000000",
      "updated_at": "2023-01-23T04:56:07.000Z",
      "updated_by": "IBMid-0000000000"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Adapter(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Delete a KMIP Adapter

                      Deletes a KMIP Adapter, including all its client certificates, with the given id / name.

                      DELETE /api/v2/kmip_adapters/{id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.delete

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.delete

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Status Code

                      • 204

                        The KMIP Adapter was successfully deleted. No content.

                      • 400

                        The KMIP Adapter could not be deleted due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        The kmip adapter with that id / name could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Adapter(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      List KMIP objects of a KMIP Adapter

                      List KMIP objects of a KMIP Adapter.

                      GET /api/v2/kmip_adapters/{adapter_id}/kmip_objects

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.list

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.list

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • adapter_id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      Query Parameters

                      • limit
                        integer

                        The number of kmip objects to retrieve. By default, GET /kmip_adapters/{id}/kmip_objects returns the first 100 kmip_objects. To retrieve a different set of kmip objects, use limit with offset to page through your available resources. The maximum value for limit is 5000. Usage: If you have 20 kmip objects associated with your KMIP adapter, and you want to retrieve only the first 5 kmip objects, use ../kmip_adapters/{id}/kmip_objects?limit=5.

                        Possible values: 1 ≤ value ≤ 5000

                        Default: 100

                      • offset
                        integer

                        The number of kmip objects to skip. By specifying offset, you retrieve a subset of kmip objects that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have 20 kmip objects associated with your KMIP adapter, and you want to retrieve kmip objects 11 through 15, use ../kmip_adapters/{id}/kmip_objects?offset=10&limit=5.

                        Possible values: value ≥ 0

                        Default: 0

                      • totalCount
                        boolean

                        If set to true, returns totalCount in the response metadata for use with pagination. The totalCount value returned specifies the total number of kmip objects that match the request, disregarding limit and offset. The default is set to false. Usage: To return the totalCount value for use with pagination, use ../kmip_adapters/{id}/kmip_objects?totalCount=true.

                      • state
                        integer[]

                        List of states to filter the KMIP objects on. The default is set to [1,2,3,4]. States are integers and correspond to Pre-Active = 1, Active = 2, Deactivated = 3, Compromised = 4, Destroyed = 5, Destroyed Compromised = 6. Usage: To filter on multiples state values, use ../kmip_adapters/{id}/kmip_objects?state=2,3.

                        Possible values: 0 ≤ number of items ≤ 4, 1 ≤ value ≤ 6

                        Default: [1,2,3,4]

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>/kmip_objects   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Response Body

                      ListKMIPObjectsWithTotalCount

                      The base schema for listing kmip objects in a kmip adapter with total count.

                      Status Code

                      • 200

                        List of KMIP objects associated with the KMIP Adapter.

                      • 400

                        The KMIP Objects could not be retrieved due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        The KMIP Objects could not be retrieved because a resource could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_object+json",
    "collectionTotal": 2,
    "totalCount": 4
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "kmip_object_type": 2,
      "state": 3,
      "created_at": "2000-01-23T04:56:07.000Z",
      "created_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab",
      "created_by": "IBMid-0000000001",
      "updated_at": "2000-02-23T08:19:00.000Z",
      "updated_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab",
      "updated_by": "IBMid-0000000001"
    },
    {
      "id": "beddecaf-0000-0000-0000-1234567890ab",
      "kmip_object_type": 2,
      "state": 5,
      "created_at": "2000-01-23T04:56:07.000Z",
      "created_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab",
      "created_by": "IBMid-0000000001",
      "updated_at": "2000-03-25T04:56:07.000Z",
      "updated_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab",
      "updated_by": "IBMid-0000000001",
      "destroyed_at": "2000-03-28T04:56:07.000Z",
      "destroyed_by": "IBMid-0000000001"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `adapter_id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "adapter_id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Object(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Retrieve a KMIP object from a KMIP Adapter

                      Retrieves a KMIP object from a KMIP Adapter by its id.

                      GET /api/v2/kmip_adapters/{adapter_id}/kmip_objects/{id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.read

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.read

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • adapter_id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • id
                        Required*
                        string

                        The v4 UUID of the kmip object that uniquely identifies it.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>/kmip_objects/<id>   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Response Body

                      ListKMIPObjectsWithTotalCount

                      The base schema for listing kmip objects in a kmip adapter with total count.

                      Status Code

                      • 200

                        The KMIP object associated with the given id in the KMIP Adapter.

                      • 400

                        The KMIP object could not be retrieved due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        The KMIP object could not be retrieved because a resource could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_object+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "kmip_object_type": 2,
      "state": 3,
      "created_at": "2000-01-23T04:56:07.000Z",
      "created_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab",
      "created_by": "IBMid-0000000000",
      "updated_at": "2000-01-23T04:56:07.000Z",
      "updated_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab",
      "updated_by": "IBMid-0000000000"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `adapter_id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "adapter_id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The id of the kmip object could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a valid UUID",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Object(s) could not be retrieved: Please see `reasons` for more details (KMIP_OBJECT_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_OBJECT_NOT_FOUND_ERR",
          "message": "kmip_object does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Object(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Delete a KMIP object from a KMIP Adapter

                      Deletes a KMIP object from a KMIP Adapter given its id. Changes the state of the KMIP object to 5 (Destroyed) and erases its key material. Any data encrypted by this KMIP object will be crypto erased when the KMIP Object changes it state to 5 (Destroyed).

                      DELETE /api/v2/kmip_adapters/{adapter_id}/kmip_objects/{id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.delete

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.delete

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • adapter_id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • id
                        Required*
                        string

                        The name or v4 UUID of the client certificate that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      Query Parameters

                      • force
                        boolean

                        Force delete the KMIP object, regardless of the object's state. All object data is eligible to be purged 90 days after deletion.

                        Default: false

                      • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>/kmip_objects/<id>   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Status Code

                      • 204

                        Delete succeeded and no content is returned.

                      • 400

                        The KMIP object associated with the KMIP Adapter could not be deleted due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        KMIP object could not be deleted because a resource could not be found.

                      • 409

                        KMIP object could not be deleted because there is a conflict. KMIP_OBJECT_NONDELETABLE_STATE_ERR: The kmip object is not in pre-active, deactivated, or compromised state

                      • 410

                        KMIP object could not be deleted because the resource is already deleted.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `adapter_id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "adapter_id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The id of the kmip object could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a valid UUID",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_OBJECT_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_OBJECT_NOT_FOUND_ERR",
          "message": "kmip_object does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_OBJECT_NONDELETABLE_STATE_ERR)",
      "reasons": [
        {
          "code": "KMIP_OBJECT_NONDELETABLE_STATE_ERR",
          "message": "The kmip object is not in pre-active, deactivated, or compromised state",
          "status": 409
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_OBJECT_DELETED_ERR)",
      "reasons": [
        {
          "code": "KMIP_OBJECT_DELETED_ERR",
          "message": "The kmip object has already been deleted: Please delete references to this kmip object",
          "status": 410
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      List client certificates of a KMIP Adapter

                      List client certificates of a KMIP Adapter.

                      GET /api/v2/kmip_adapters/{adapter_id}/certificates

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.list

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.list

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • adapter_id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      Query Parameters

                      • limit
                        integer

                        The number of client certificates to retrieve. By default, GET /kmip_adapters/{id}/certificates returns the first 100 certificates. To retrieve a different set of certificates, use limit with offset to page through your available resources. The maximum value for limit is 200. Usage: If you have 20 certificates associated with your KMIP adapter, and you want to retrieve only the first 5 certificates, use ../kmip_adapters/{id}/certificates?limit=5.

                        Possible values: 1 ≤ value ≤ 200

                        Default: 100

                      • offset
                        integer

                        The number of client certificates to skip. By specifying offset, you retrieve a subset of certificates that starts with the offset value. Use offset with limit to page through your available resources. Usage: If you have 20 certificates associated with your KMIP adapter, and you want to retrieve certificates 11 through 15, use ../kmip_adapters/{id}/certificates?offset=10&limit=5.

                        Possible values: value ≥ 0

                        Default: 0

                      • totalCount
                        boolean

                        If set to true, returns totalCount in the response metadata for use with pagination. The totalCount value returned specifies the total number of client certificates that match the request, disregarding limit and offset. The default is set to false. Usage: To return the totalCount value for use with pagination, use ../kmip_adapters/{id}/certificates?totalCount=true.

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>/certificates   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Response Body

                      ListKMIPPartialClientCertificatesWithTotalCount

                      The base schema for listing client certificates in a kmip adapter with total count.

                      Status Code

                      • 200

                        List of client certificates associated with the KMIP Adapter.

                      • 400

                        The client certificates could not be retrieved due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        The client certificates could not be retrieved because a resource could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_client_certificate+json",
    "collectionTotal": 2,
    "totalCount": 4
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "name": "kmip-client-certificate",
      "created_at": "2000-01-23T04:56:07.000Z",
      "created_by": "IBMid-0000000000"
    },
    {
      "id": "beddecaf-0000-0000-0000-1234567890ab",
      "name": "kmip-client-certificate2",
      "created_at": "2001-01-23T04:56:07.000Z",
      "created_by": "IBMid-0000000001"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `adapter_id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "adapter_id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Client Certificate(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Add a client certificate to a KMIP Adapter

                      Add a client certificate to a KMIP Adapter. It might take up to 5 minutes for a KMIP call using the newly add certificate to pass authentication. A maximum of 200 client certificates can be associated with a KMIP Adapter at a time.

                      POST /api/v2/kmip_adapters/{adapter_id}/certificates

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.create

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.create

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • adapter_id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      Request Body

                      Required*
                      CreateKMIPClientCertificateRequestBody

                      Properties of a client certificate that must be provided during creation

                      • curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>/certificates   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'   -d '{
      "metadata": {
          "collectionTotal": 1,
          "collectionType": "application/vnd.ibm.kms.kmip_client_certificate+json"
      },
      "resources": [
          {
              "name": "<name>",
              "certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----"
          }
      ]
  }'

                      Response

                      Response Body

                      ListKMIPClientCertificates

                      The base schema for listing client certificates in a kmip adapter.

                      Status Code

                      • 201

                        The full details of the KMIP Certificate just created

                      • 400

                        A client certificate could not be added to the KMIP Adapter due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        Certificate could not be created because a resource could not be found.

                      • 409

                        KMIP_CERT_QUOTA_ERR: The quota for certificates in this KMIP adapter instance has been reached. Unable to add any more certificates KMIP_CERT_DUPLICATE_NAME_ERR: There is a kmip client certificate in this kms adapter with the same name. Please choose a different name KMIP_CERT_DUPLICATE_ERR: The certificate payload is already associated with this adapter KMIP_CERT_REUSE_ERR: Another KMIP adapter reserves exclusive use of this certificate payload

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_client_certificate+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "name": "kmip-client-certificate",
      "certificate": "-----BEGIN CERTIFICATE-----\\nAAA\\n-----END CERTIFICATE-----",
      "created_at": "2000-01-23T04:56:07.000Z",
      "created_by": "IBMid-0000000000"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: KMIP Certificate could not be added. See 'reasons' for more details.",
      "reasons": [
        {
          "code": "INVALID_FIELD_ERR",
          "message": "The field '<name|certificate>' has an invalid format. Please refer to https://cloud.ibm.com/apidocs/key-protect.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "field",
            "name": "<name|certificate>"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Client Certificate could not be created: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)",
      "reasons": [
        {
          "code": "KMIP_CERT_QUOTA_ERR",
          "message": "The quota for certificates in this KMIP instance  has been reached. Unable to add any more certificates.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)",
      "reasons": [
        {
          "code": "KMIP_CERT_DUPLICATE_NAME_ERR",
          "message": "There is a certificate in this kmip  adapter with the same name. Please choose a different name",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)",
      "reasons": [
        {
          "code": "KMIP_CERT_DUPLICATE_ERR",
          "message": "The certificate payload is already associated with this adapter.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)",
      "reasons": [
        {
          "code": "KMIP_CERT_REUSE_ERR",
          "message": "Another KMIP adapter reserves exclusive use of this certificate payload.",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Retrieve a client certificate from a KMIP Adapter

                      Retrieves a client certificate from a KMIP Adapter using its id / name.

                      GET /api/v2/kmip_adapters/{adapter_id}/certificates/{id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.read

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.read

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • adapter_id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • id
                        Required*
                        string

                        The name or v4 UUID of the client certificate that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>/certificates/<certificate_name>   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Response Body

                      ListKMIPClientCertificates

                      The base schema for listing client certificates in a kmip adapter.

                      Status Code

                      • 200

                        The full details of the KMIP Certificate with the given id / name

                      • 400

                        The client certificate associated with the KMIP Adapter could not be retrieved due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        Certificate could not be retrieved because a resource could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.kmip_client_certificate+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "feddecaf-0000-0000-0000-1234567890ab",
      "name": "kmip-client-certificate",
      "certificate": "-----BEGIN CERTIFICATE-----\\nAAA\\n-----END CERTIFICATE-----",
      "created_at": "2000-01-23T04:56:07.000Z",
      "created_by": "IBMid-0000000000"
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `adapter_id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "adapter_id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The name of the client certificate could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a v4 UUID or a string matching pattern `^[a-zA-Z0-9-]*$`.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Client Certificate could not be retrieved: Please see `reasons` for more details (KMIP_CLIENT_CERTIFICATE_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_CLIENT_CERTIFICATE_NOT_FOUND_ERR",
          "message": "kmip_client_certificate does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Client Certificate(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}

                      Delete a client certificate from a KMIP Adapter

                      Removes a client certificate from a KMIP Adapter given its id / name. It might take up to 5 minutes for a KMIP call using deleted certificate to fail authentication.

                      DELETE /api/v2/kmip_adapters/{adapter_id}/certificates/{id}

                      Authorization

                      To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

                      • kms.kmip-management.delete

                      Auditing

                      Calling this method generates the following auditing event.

                      • kms.kmip-management.delete

                      Request

                      Custom Headers

                      • Bluemix-Instance
                        Required*
                        string

                        The IBM Cloud instance ID that identifies your Key Protect service instance.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      • Correlation-Id
                        string

                        The v4 UUID used to correlate and track transactions.

                        Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

                      Path Parameters

                      • adapter_id
                        Required*
                        string

                        The name or v4 UUID of the KMIP Adapter that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • id
                        Required*
                        string

                        The name or v4 UUID of the client certificate that uniquely identifies it.

                        Possible values: 2 ≤ length ≤ 40, Value must match regular expression ^[a-zA-Z0-9-_]{2,40}$

                      • curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/kmip_adapters/<adapter_name>/certificates/<certificate_name>   -H 'accept: application/json'   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

                      Response

                      Status Code

                      • 204

                        Delete succeeded and no content is returned.

                      • 400

                        The client certificate associated with the KMIP Adapter could not be deleted due to invalid request data.

                      • 401

                        Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.

                      • 404

                        Certificate could not be retrieved because a resource could not be found.

                      • 429

                        Too many requests. Wait a few minutes and try again.

                      • 500

                        IBM Key Protect is currently unavailable. Your request could not be processed. Try again later. If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

                      Example responses
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `adapter_id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$",
          "status": 400,
          "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "adapter_id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "The name of the client certificate could not be validated. See `reasons` for more details.",
      "reasons": [
        {
          "code": "INVALID_PATH_PARAM_ERR",
          "message": "The path_param `id` must be: a v4 UUID or a string matching pattern `^[a-zA-Z0-9-]*$`.",
          "status": 400,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect",
          "target": {
            "type": "path_param",
            "name": "id"
          }
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Client Certificate could not be retrieved: Please see `reasons` for more details (KMIP_CLIENT_CERTIFICATE_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_CLIENT_CERTIFICATE_NOT_FOUND_ERR",
          "message": "kmip_client_certificate does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: KMIP Client Certificate could not be deleted: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)",
      "reasons": [
        {
          "code": "KMIP_ADAPTER_NOT_FOUND_ERR",
          "message": "kmip_adapter does not exist",
          "status": 404
        }
      ]
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Wait a few minutes and try again."
    }
  ]
}
                      • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later."
    }
  ]
}
                      id=curlclassName=tab-item-selected