IBM Key Protect API - IBM Cloud API Docs

Introduction

Last updated: 2021-05-07

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 endpoint URL with a service endpoint, the API_KEY with the API key associated with your application, the TokenURL with your Cloud IAM token, and InstanceID with the IBM Cloud instance ID that identifies your Key Protect service instance.

The value kp.DefaultTokenURL for TokenURL defaults to IAM production URL. 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 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"

    "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
    }
}

Replace the key_protect_url with the API endpoint.

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 informaton, see Regions and locations.

Replace <api_key> with your service credentials. Replace the <instance_ID> with the Key Protect service instance ID.

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:

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.

Event tracking

You can monitor API activity within your account by using the IBM Cloud Activity Tracker with LogDNA service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker with LogDNA.

The specific event type is listed for each individual method. For more information about how to track Certificate Manager activity, see Auditing 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.

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

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]
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.

Default: default

Request Body

Required*

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

The base request for creating a new key.

Example:

CreateRootKey

Example request

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": "...",
        "extractable": false
      }
    ]
  }'

Example request

package main

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

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

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

Example request

// 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);

Example request

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"])

Example request

// 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
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.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 201

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": false,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "keyVersion": {
        "id": "...",
        "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key is missing a required field."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 409

{
  "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'."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

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]
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.

Example request

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>'

Example request

package main

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

  "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("Get Keys failed with error: ", err)
    return
  }
  b, _ := json.MarshalIndent(keys, "", "  ")
  fmt.Println(string(b))
}

Example request

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"]))

Example request

// 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);
}

Example request

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.
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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "keyVersion": {
        "id": "...",
        "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Standard-key",
      "description": "...",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Deleted-Standard-key",
      "description": "...",
      "state": 5,
      "extractable": true,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": true,
      "deletionDate": "YYYY-MM-DDTHH:MM:SSZ",
      "restoreAllowed": true,
      "restoreExpirationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "purgeAllowed": false,
      "purgeAllowedFrom": "YYYY-MM-DDTHH:MM:SSZ",
      "purgeScheduledOn": "YYYY-MM-DDTHH:MM:SSZ"
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

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]
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.

Example request

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.

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID or alias that uniquely identifies the key

Example request

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>'

Example request

package main

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

  "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("Get Key failed with error: ", err)
    return
  }
  b, _ := json.MarshalIndent(key, "", "  ")
  fmt.Println(string(b))
}

Example request

// 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]);

Example request

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"]))

Example request

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Standard-key",
      "description": "...",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "keyVersion": {
        "id": "...",
        "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false,
      "payload": "..."
    }
  ]
}

Status 400

{
  "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."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "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."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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:

disable: Disable operations for a key
enable: Enable operations for a key
restore: Restore a root key
rewrap: Use a root key to rewrap or reencrypt a data encryption key
rotate: Create a new version of a root key
setKeyForDeletion: Authorize deletion for a key with a dual authorization policy
unsetKeyForDeletion: [Remove an authorization]((/docs/key-protect?topic=key-protect-delete-dual-auth-keys#unset-key-deletion-api) for a key with a dual authorization policy
unwrap: Use a root key to unwrap or decrypt a data encryption key
wrap: Use a root key to wrap or encrypt 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}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Query Parameters

action
Required*
string
The action to perform on the specified key.

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

Request Body

Required*

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

The base request for key actions.

Example:

WrapKey

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. Please delete references to this key.
422
The ciphertext provided for the unwrap operation was not wrapped by this key.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=",
  "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9",
  "keyVersion": {
    "id": "..."
  }
}

Status 201

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": false,
      "keyRingID": "default",
      "crn": "...",
      "imported": true,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "keyVersion": {
        "id": "...",
        "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false
    }
  ]
}

Status 400

{
  "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."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found."
    }
  ]
}

Status 409

{
  "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."
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Please delete references to this key."
    }
  ]
}

Status 422

{
  "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."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Request Body

application/vnd.ibm.kms.key+jsonPatchKeyRequestBody

The base request for patch key.

Examples:

View

Example request

curl -X PATCH   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>   -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"
  }'

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
The key could not be found.
410
The requested key was previously deleted and is no longer available. Please delete references to this key.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": false,
      "keyRingID": "new-key-ring-id",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "keyVersion": {
        "id": "...",
        "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found."
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Please delete references to this key."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

Deletes a key by specifying the ID 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: When you delete a key, you permanently shred its contents and associated data. The action cannot be reversed.

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

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

Example request

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

Example request

package main

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

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

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

Example request

// Initialize the Key Protect client as specified in Authentication

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

Example request

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)

Example request

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.
204
The key was successfully deleted. No content.
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. Please delete references to this key.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 5,
      "extractable": false,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": true,
      "deletionDate": "YYYY-MM-DDTHH:MM:SSZ",
      "deletedBy": "...",
      "restoreAllowed": true,
      "restoreExpirationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "purgeAllowed": false,
      "purgeAllowedFrom": "YYYY-MM-DDTHH:MM:SSZ",
      "purgeScheduledOn": "YYYY-MM-DDTHH:MM:SSZ"
    }
  ]
}

Status 400

{
  "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."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found."
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key could not be deleted. Please '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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Please delete references to this key."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.secrets.readmetadata

Auditing

Calling this method generates the following auditing event.

kms.secrets.readmetadata

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID or alias that uniquely identifies the key

Example request

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>'

Example request

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 key with specified ID could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Standard-key",
      "description": "...",
      "state": 1,
      "extractable": true,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false
    }
  ]
}

Status 400

{
  "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."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key metadata could not be retrieved. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

Purge all key metadata and registrations associated with the specified key. Purge 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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Example request

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

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
The key could not be purged because it is not in the Destroyed (5) state or purge is not allowed due to wait period of four hours has not been reached.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 5,
      "extractable": false,
      "keyRingID": "default",
      "crn": "...",
      "imported": false,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": true,
      "deletionDate": "YYYY-MM-DDTHH:MM:SSZ",
      "deletedBy": "...",
      "purgeAllowed": true,
      "purgeAllowedFrom": "YYYY-MM-DDTHH:MM:SSZ",
      "purgeScheduledOn": "YYYY-MM-DDTHH:MM:SSZ"
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key cannot be purged due to a malformed ID."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found."
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key could not be purged. Please '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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

Restore a key.

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Request Body

application/vnd.ibm.kms.key_action_restore+jsonRestoreKeyRequestBody

The base request parameters for restore key action.

Examples:

RestoreKey

SecureRestoreKey

Example restore key request

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": "<key_material>"
      }
    ]
  }'

Example secure import restore key request

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"
      }
    ]
  }'

Example restore key request

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
The requested key is not in the Destroyed (5) state or the state of the key has changed within the last 30 seconds.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 201

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": false,
      "keyRingID": "default",
      "crn": "...",
      "imported": true,
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": 256,
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 256,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ",
      "keyVersion": {
        "id": "...",
        "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "dualAuthDelete": {
        "enabled": true,
        "keySetForDeletion": true,
        "authExpiration": "YYYY-MM-DDTHH:MM:SSZ"
      },
      "deleted": false
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be restored: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be restored: Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

Retrieves all versions of a root key by specifying the ID 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 stered 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 > name > Access policies.

kms.secrets.listkeyversions

Auditing

Calling this method generates the following auditing event.

kms.secrets.listkeyversions

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

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

Example request

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

Example request

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;
}

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. Please delete references to this key.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "id": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
    },
    {
      "id": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ"
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found."
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: The key is not in an active state."
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Please delete references to this key."
    }
  ]
}

Use a root key to wrap or encrypt a data encryption key.

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Request Body

application/vnd.ibm.kms.key_action_wrap+jsonWrapKeyRequestBody

The base request for wrap key action.

Examples:

View

Example wrap request (generated DEK)

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'

Example wrap request with provided plaintext

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>"]
  }'

Example wrap request

package main

import (
  "context"
  "fmt"

  "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))
}

Example wrap request

// 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>";
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

Example wrap request

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=",
  "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9",
  "keyVersion": {
    "id": "...",
    "creationDate": "2010-01-12T05:23:19+0000"
  }
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Wrap with key could not be performed: Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Wrap with key could not be performed: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Wrap with key could not be performed: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Wrap with key could not be performed: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Request Body

Required*

application/vnd.ibm.kms.key_action_unwrap+jsonUnwrapKeyRequestBody

The base request for unwrap key action.

Examples:

View

Example unwrap request

curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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>"]
  }'

Example unwrap request

package main

import (
  "context"
  "fmt"

  "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))
}

Example unwrap request

// Initialize the Key Protect client as specified in Authentication

const unwrapKeyParams = Object.assign({}, envConfigs);
unwrapKeyParams.id = "<key_id>";
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

Example unwrap request

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=",
  "keyVersion": {
    "id": "...",
    "creationDate": "2010-01-12T05:23:19+0000"
  }
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Unwrap with key could not be performed: Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Unwrap with key could not be performed: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Wrap action could not be performed with the key: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Unwrap with key could not be performed: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 422

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unprocessable Entity: Unwrap with key could not be performed: Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Request Body

Required*

application/vnd.ibm.kms.key_action_rewrap+jsonRewrapKeyRequestBody

The base request for rewrap key action.

Examples:

View

Example request

curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9",
  "keyVersion": {
    "id": "...",
    "creationDate": "2010-01-12T05:23:19+0000"
  },
  "rewrappedKeyVersion": {
    "id": "...",
    "creationDate": "2010-01-12T05:23:19+0000"
  }
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Rewrap with key could not be performed: Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Rewrap with key could not be performed: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Rewrap with key could not be performed: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Rewrap with key could not be performed: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 422

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unprocessable Entity: Rewrap with key could not be performed: Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Request Body

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

The base request for rotate key action.

Example:

RotateKey

Example key rotate request

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>'

Example imported key rotate request

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>"
  }'

Example secure imported key rotate request

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"
  }'

Example key rotate request

package main

import (
 "context"
 "fmt"

 "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
The key could not be found.
409
The requested key is not in the Active (1) or Deactivated (3) state or has been rotated within the last hour.
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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Key could not be rotated: Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be rotated: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be rotated: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key could not be rotated: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Example set key for deletion request

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

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
The key could not be found.
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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key deletion could not be scheduled: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key deletion could not be scheduled: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key deletion could not be scheduled: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Example unset key for deletion request

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

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
The key could not be found.
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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key deletion could not be cancelled: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key deletion could not be cancelled: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key deletion could not be cancelled: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Example enable key request

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

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
The requested key is not in the Suspended (2) state or the state of the key has changed within the last 30 seconds.
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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Key could not be enabled: Please 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"
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be enabled: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be enabled: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key could not be enabled: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Example disable key request

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

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Key could not be disabled: Please 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"
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Key could not be disabled: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Key could not be disabled: Please 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"
        }
      ]
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: Key could not be disabled: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "KEY_DELETED_ERR",
          "message": "Key has already been deleted. Please delete references to this key",
          "status": 410,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

Initiate a manual data synchronization request to the associated resources of a key. Regular key lifecycle events automatically notify integrated services of the change, however, in the case a service does not respond to a key lifecycle event notification, 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 up-to-date records of the key state and version. Key Protect does not have the ability to force data synchronization for other services. The sync API is purely to initiate a request for all associated resources to synchronize their key records with what the Key Protect API returns.

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Example sync associated resources request

curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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
The key could not be found.
409
The key has been synced or updated (i.e. rotated, restored, disabled, enabled, deleted) within the last hour.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: Associated resources could not be synced: Please 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"
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Associated resources could not be synced: Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Conflict: Associated resources could not be synced: Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "REQ_TOO_EARLY_ERR",
          "message": "The key was updated recently: Please wait and try again",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Query Parameters

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

Allowable values: [dualAuthDelete,rotation]

Request Body

Required*

One of

The base request for key policy create or update.

Example:

policies

Example request

curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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": {
          "interval_month": <rotation_interval>
        }
      },
      {
        "type": "application/vnd.ibm.kms.policy+json",
        "dualAuthDelete": {
          "enabled": <true|false>
        }
      }
    ]
  }'

Example request (dual authorization policy)

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>
        }
      }
    ]
  }'

Example request (rotation policy)

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": {
          "interval_month": <rotation_interval>
        }
      }
    ]
  }'

Example request (rotation policy)

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.SetPolicy(context.Background(), <key_ID>, kp.ReturnRepresentation, <rotation_interval>)
  if err != nil {
    fmt.Println("Error while creating policies: ", 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. Please delete references to this key.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "rotation": {
        "interval_month": 3
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    },
    {
      "id": "...",
      "crn": "...",
      "dualAuthDelete": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "dualAuthDelete": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "rotation": {
        "interval_month": 3
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Please delete references to this key."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Query Parameters

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

Allowable values: [dualAuthDelete,rotation]

Example request (all key policies)

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

Example request (dual authorization policy)

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>'

Example request (rotation policy)

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>'

Example request

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.GetPolicy(context.Background(), <key_ID>)
  if err != nil {
    fmt.Println("Error while getting policies: ", 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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "rotation": {
        "interval_month": 3
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    },
    {
      "id": "...",
      "crn": "...",
      "dualAuthDelete": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "dualAuthDelete": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "rotation": {
        "interval_month": 3
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.instancepolicies.write

Auditing

Calling this method generates the following auditing event.

kms.instancepolicies.write

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.

Query Parameters

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

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

Request Body

Required*

One of

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

Example:

policies

Example request

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": 4
    },
    "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>
        }
      }
    ]
  }'

Example request (allowed network policy)

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>"
          }
        }
      }
    ]
  }'

Example request (dual authorization policy)

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>
        }
      }
    ]
  }'

Example request (metrics)

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>
        }
      }
    ]
  }'

Example request (allowed IP policy)

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"]
          }
        }
      }
    ]
  }'

Example request (key create and import access policy)

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>
          }
        }
      }
    ]
  }'

Example request (dual authorization policy)

package main

import (
  "context"
  "fmt"

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

func main() {
  // Initialize the Key Protect client as specified in Authentication
  err = api.SetInstancePolicies(context.Background(), <true|false>)
  if err != nil {
    fmt.Println("Error while creating policies: ", err)
    return
  }
  fmt.Println("Instance policy set successfully")
}

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
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. Please delete references to this key.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 410

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Please delete references to this key."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.instancepolicies.read

Auditing

Calling this method generates the following auditing event.

kms.instancepolicies.read

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.

Query Parameters

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

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

Example request

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>'

Example request (allowed network policy)

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>'

Example request (dual authorization policy)

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>'

Example request (allowedIP)

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>'

Example request (key create and import access policy)

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>'

Example request (metrics)

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>'

Example request

package main

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

  "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))
}

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 4
  },
  "resources": [
    {
      "policy_type": "allowedNetwork",
      "policy_data": {
        "enabled": "<true|false>",
        "attributes": {
          "allowed_network": "<public-and-private|private-only>"
        }
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    },
    {
      "policy_type": "dualAuthDelete",
      "policy_data": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    },
    {
      "policy_type": "metrics",
      "policy_data": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    },
    {
      "policy_type": "allowedIP",
      "policy_data": {
        "enabled": "<true|false>",
        "attributes": {
          "allowed_ip": [
            "X.X.X.X/N",
            "..."
          ]
        }
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    },
    {
      "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>"
        }
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    }
  ]
}

Status 200

{
  "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>"
        }
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    }
  ]
}

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "dualAuthDelete",
      "policy_data": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    }
  ]
}

Status 200

{
  "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",
            "..."
          ]
        }
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    }
  ]
}

Status 200

{
  "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>"
        }
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    }
  ]
}

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "policy_type": "metrics",
      "policy_data": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdated": "..."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.instance.readallowedipport

Auditing

Calling this method generates the following auditing event.

kms.policies.readallowedipport

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.

Example request

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'

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.allowed_ip_metadata+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "private_endpoint_port": 8888
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.importtoken.create

Auditing

Calling this method generates the following auditing event.

kms.importtoken.create

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Default: default

Request Body

Required*

ImportToken

The base request to create an import token.

Example request

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>
  }'

Example request

package main

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

  "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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "expirationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "maxAllowedRetrievals": 10,
  "remainingRetrievals": 10
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.importtoken.read

Auditing

Calling this method generates the following auditing event.

kms.importtoken.read

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Default: default

Example request

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'

Example request

package main

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

  "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
An import token was not found in the specified service instance. To create an import token, use POST /import_token
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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "expirationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "maxAllowedRetrievals": 10,
  "remainingRetrievals": 9,
  "payload": "...",
  "nonce": "..."
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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)"
    }
  ]
}

Status 404

{
  "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'"
    }
  ]
}

Status 409

{
  "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'."
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.
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.

Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f59bcbfa6ea2f006b4ed7094c1a08dcdd%3a1a0ec336-f391-4091-a6fb-5e084a4c56f4%3a%3abucket

Request Body

CreateRegistration

The base request for creating a registration.

Examples:

View

Example request

curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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": true,
        "description": "..."
      }
    ]
  }'

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "string",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "string",
      "creationDate": "2010-01-12T05:23:19+0000",
      "updatedBy": "string",
      "lastUpdated": "2010-01-12T05:23:19+0000",
      "description": "string",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "string",
        "creationDate": "2010-01-12T05:23:19+0000"
      }
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. Please 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": "param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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"
        }
      ]
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. Please see 'reasons' for more details",
      "reasons": [
        {
          "code": "REGISTRATION_DUP_ERR",
          "message": "Registration already exists",
          "status": 409,
          "moreInfo": "https://cloud.ibm.com/apidocs/key-protect"
        }
      ]
    }
  ]
}

Status 422

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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.

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.
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.

Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f59bcbfa6ea2f006b4ed7094c1a08dcdd%3a1a0ec336-f391-4091-a6fb-5e084a4c56f4%3a%3abucket

Request Body

Required*

UpdateRegistration

The base request for updating a registration.

Examples:

View

Example request

curl -X PATCH   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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": true
      }
    ]
  }'

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "string",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "string",
      "creationDate": "2010-01-12T05:23:19+0000",
      "updatedBy": "string",
      "lastUpdated": "2010-01-12T05:23:19+0000",
      "description": "string",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "string",
        "creationDate": "2010-01-12T05:23:19+0000"
      }
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be updated. Please 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": "param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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"
        }
      ]
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be updated. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.
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.

Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f59bcbfa6ea2f006b4ed7094c1a08dcdd%3a1a0ec336-f391-4091-a6fb-5e084a4c56f4%3a%3abucket

Request Body

Required*

ReplaceRegistration

The base request for replacing a registration.

Examples:

View

Example request

curl -X PUT   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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": true,
        "description": "...",
        "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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "string",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "string",
      "creationDate": "2010-01-12T05:23:19+0000",
      "updatedBy": "string",
      "lastUpdated": "2010-01-12T05:23:19+0000",
      "description": "string",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "string",
        "creationDate": "2010-01-12T05:23:19+0000"
      }
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be replaced. Please 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": "param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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"
        }
      ]
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be replaced. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.
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.

Example: crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f59bcbfa6ea2f006b4ed7094c1a08dcdd%3a1a0ec336-f391-4091-a6fb-5e084a4c56f4%3a%3abucket

Example request

curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "keyId": "string",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "string",
      "creationDate": "2010-01-12T05:23:19+0000",
      "updatedBy": "string",
      "lastUpdated": "2010-01-12T05:23:19+0000",
      "description": "string",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "string",
        "creationDate": "2010-01-12T05:23:19+0000"
      }
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. Please 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": "param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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"
        }
      ]
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.
Prefer
string
Alters server behavior for POST or DELETE operations. A header with return=minimal causes the service to return only the key identifier, or 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]

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

Query Parameters

action
Required*
string
The action to perform on the specified key.

Allowable values: [deactivate]

Request Body

Required*

DeactivateRegistration

The base request for registration actions.

Examples:

DeactivateRegistration

Example deactivate request

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.resource_crn+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/684b6eb4-33b6-42e7-9b82-ca6cb8b59dac:b016015c-95b3-4ffd-b5ab-8316ee83ba79:bucket:mybucket"
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Action could not be performed on registration. Please 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": "param",
            "name": "urlEncodedResourceCRNQuery"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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"
        }
      ]
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Action could not be performed on registration. Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resource": [
    {
      "errorMsg": "Action could not be performed on registration. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.

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.

Example: crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F274074dce64e9c423ffc238516c755e1%3A29caf0e7-120f-4da8-9551-3abf57ebcfc7%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.

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.

Example request

curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/registrations   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 2,
    "totalCount": 4
  },
  "resources": [
    {
      "keyId": "7f19bee1-4fdf-4646-866e-111c80f94478",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "IBMid-203BRNKPR5",
      "creationDate": "2019-12-03T05:23:19+0000",
      "updatedBy": "IBMid-203BRNKPR5",
      "lastUpdated": "2019-12-03T05:23:19+0000",
      "description": "Registration between a bucket and root key",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "4a0225e9-17a0-46c1-ace7-f25bcf4237d4",
        "creationDate": "2019-12-03T05:23:19+0000"
      }
    },
    {
      "keyId": "7f19bee1-4fdf-4646-866e-111c80f94478",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<other-bucket-name>",
      "createdBy": "IBMid-203BRNKPR5",
      "creationDate": "2019-12-02T06:15:00+0000",
      "updatedBy": "IBMid-203BRNKPR5",
      "lastUpdated": "2019-12-02T06:15:00+0000",
      "description": "Registration between the root key and a different bucket",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "4a0225e9-17a0-46c1-ace7-f25bcf4237d4",
        "creationDate": "2019-12-02T06:15:00+0000"
      }
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. Please 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": "param",
            "name": "urlEncodedResourceCRNQuery"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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"
        }
      ]
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be created. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

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.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

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.

Example: crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F274074dce64e9c423ffc238516c755e1%3A29caf0e7-120f-4da8-9551-3abf57ebcfc7%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.

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.

Example request

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>'

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.registration+json",
    "collectionTotal": 2,
    "totalCount": 4
  },
  "resources": [
    {
      "keyId": "7f19bee1-4fdf-4646-866e-111c80f94478",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<bucket-name>",
      "createdBy": "IBMid-203BRNKPR5",
      "creationDate": "2019-12-03T05:23:19+0000",
      "updatedBy": "IBMid-203BRNKPR5",
      "lastUpdated": "2019-12-03T05:23:19+0000",
      "description": "Registration between a bucket and root key",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "4a0225e9-17a0-46c1-ace7-f25bcf4237d4",
        "creationDate": "2019-12-03T05:23:19+0000"
      }
    },
    {
      "keyId": "fcc3567c-793e-455f-b576-e2989e2bb170",
      "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<service-instance>:bucket:<other-bucket-name>",
      "createdBy": "IBMid-203BRNKPR5",
      "creationDate": "2019-12-02T06:15:00+0000",
      "updatedBy": "IBMid-203BRNKPR5",
      "lastUpdated": "2019-12-02T06:15:00+0000",
      "description": "Registration between a bucket and root key",
      "preventKeyDeletion": true,
      "keyVersion": {
        "id": "f58a7cfb-2b8d-4bba-b388-cfb90c3fbf31",
        "creationDate": "2019-12-02T06:15:00+0000"
      }
    }
  ]
}

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Registration could not be deleted. Please 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": "param",
            "name": "urlEncodedResourceCRNQuery"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 403

{
  "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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.secrets.eventack

Auditing

Calling this method generates the following auditing event.

kms.secrets.eventack

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Default: default

Request Body

Required*

application/vnd.ibm.kms.event_acknowledge+jsonEventAcknowledge

The base request for acknowledging a key action events.

Examples:

SingleEvent

BatchEvents

Example key event acknowledgement

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": "2018-04-12T23:20:50.52Z",
        "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
The specified event could not be found.
429
Too many requests. Please wait a few minutes and try again.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Event acknowledgement could not be performed for this service. Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: Event acknowledgement could not be performed for this service. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Creates an 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 > name > Access policies.

kms.secrets.createalias

Auditing

Calling this method generates the following auditing event.

kms.secrets.createalias

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.
alias
Required*
string
An alias that 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 a limit of 1000 aliases per instance. Alias must be alphanumeric and cannot contain spaces or special characters other than '-' or '_'.

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. Alias size can be between 2 - 90 characters.

Example request

curl -X POST   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/aliases/<alias>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

Example request

public static List<KeyAliasResource> createKeyAlias(String keyId, String keyAlias) {
  List<KeyAliasResource> responseObj = null;
  
  try {
    // Construct an instance of the CreateKeyAliasOptions model
    CreateKeyAliasOptions createKeyAliasOptionsModel = new CreateKeyAliasOptions.Builder()
    .id(keyId)
    .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
The key with specified ID could not be found.
409
The alias is already associated with a key in the kms.

The alias quota for this key or instance has been reached and alias can not be created.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be created. Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be created. Please 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"
        }
      ]
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key alias could not be created: Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.secrets.deletealias

Auditing

Calling this method generates the following auditing event.

kms.secrets.deletealias

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.
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.

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the key.
alias
Required*
string
An alias that 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 a limit of 1000 aliases per instance. Alias must be alphanumeric and cannot contain spaces or special characters other than '-' or '_'.

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. Alias size can be between 2 - 90 characters.

Example request

curl -X DELETE   https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID>/aliases/<alias>   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/json'

Example request

public static String deleteKeyAlias (String keyId, String keyAlias) {

  // Construct an instance of the DeleteKeyAliasOptions model
  DeleteKeyAliasOptions deleteKeyAliasOptionsModel = new DeleteKeyAliasOptions.Builder()
    .id(keyId)
    .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
The alias with specified key ID could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be deleted. Please 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": "param",
            "name": "aliases"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 404

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Alias could not be deleted. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 > name > Access policies.

kms.keyrings.list

Auditing

Calling this method generates the following auditing event.

kms.keyrings.list

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.

Example list Key Rings

curl -X GET   https://<region>.kms.cloud.ibm.com/api/v2/key_rings   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'

Example list Key Rings

public static ListKeyRings getKeyRings () {
  ListKeyRings result = null;
  
  // Construct an instance of the ListKeyRingsOptions model
  ListKeyRingsOptions listKeyRingsOptionsModel = new ListKeyRingsOptions.Builder()
    .bluemixInstance("<instance_id>")
    .build();

  try {
    // Invoke operation with valid options model
    Response<ListKeyRings> response = testClient.listKeyRings(listKeyRingsOptionsModel).execute();
    return response.getResult();
  } catch (ClassCastException e) {
    return result;
  }
}

Response

Response Body

ListKeyRings

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key_ring+json",
    "collectionTotal": 3
  },
  "resources": [
    {
      "id": "default"
    },
    {
      "id": "example-key-ring",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "..."
    },
    {
      "id": "key-ring-name-2",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "createdBy": "..."
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

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 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 > name > Access policies.

kms.keyrings.create

Auditing

Calling this method generates the following auditing event.

kms.keyrings.create

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.

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-]*$

Example create Key Ring

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>'

Example create Key Ring

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. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

Delete the key ring from the instance. key ring ID default cannot be destroyed. Currently, only key rings with 0 (zero) keys, in any state [Active (1), Suspended (2), Deactivated (3), Destroyed (5)], may be deleted.

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 > name > Access policies.

kms.keyrings.delete

Auditing

Calling this method generates the following auditing event.

kms.keyrings.delete

Request

Custom Headers

Bluemix-Instance
Required*
string
The IBM Cloud instance ID that identifies your Key Protect service instance.
Correlation-Id
string
The v4 UUID used to correlate and track transactions.

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-]*$

Example delete Key Ring

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>'

Example delete Key Ring

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
The specified key ring contains at least one key (in any state)
429
Too many requests. Please wait a few minutes and try again.
500
IBM Key Protect is currently unavailable. Your request could not be processed. Please try again later.

If the problem persists, note the correlation-ID in the response header and contact IBM Cloud support.

Example responses

Status 400

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. Please 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"
          }
        }
      ]
    }
  ]
}

Status 401

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Unauthorized: The user does not have access to the specified resource"
    }
  ]
}

Status 409

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Key ring could not be created. Please 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"
        }
      ]
    }
  ]
}

Status 429

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}

Status 500

{
  "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. Please try again later."
    }
  ]
}

Introduction

Authentication

Event tracking

Error handling

Metadata

Pagination

Methods

Create a key

Authorization

Auditing

Request

Custom Headers

Bluemix-Instance

Correlation-Id

Prefer

X-Kms-Key-Ring

Request Body

metadata

resources

Response

Response Body

metadata

resources

Status Code

201

400

401

403

409

429

500

List keys

Authorization

Auditing

Request

Custom Headers

Bluemix-Instance

Correlation-Id

X-Kms-Key-Ring

Query Parameters

limit

offset

state

extractable

Response

Response Body

metadata

resources

Status Code

200

401

429

500

Retrieve key total

Authorization

Auditing

Request

Custom Headers

Bluemix-Instance

Correlation-Id

X-Kms-Key-Ring

Query Parameters

state

extractable

Response

Response Headers

Key-Total

Status Code

200

401

403

429

500

Retrieve a key

Authorization

Auditing

Request

Custom Headers

Bluemix-Instance

Correlation-Id