Introduction

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

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.

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.

Authentication

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.

To retrieve your access token:

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

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 retrieve your access token:

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://iam.cloud.ibm.com/identity/token",
  "method": "POST",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "application/json"
  },
  "data": "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

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 retrieve your access token:

import requests

url = "https://iam.cloud.ibm.com/identity/token"

headers = {
  "Content-Type": "application/x-www-form-urlencoded",
  "Accept": "application/json",
}

data = [
  ("grant_type", "urn:ibm:params:oauth:grant-type:apikey"),
  ("apikey", "<API_KEY>"),
]

response = requests.request("POST", url, headers=headers, data=data)

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.

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.

Methods

Create a new key

Creates a new key with specified key material.

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

POST /api/v2/keys
Request

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

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

The base request for creating a new key.

Response

Status Code

  • The key was successfully created.

  • The key is missing a required field.

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Retrieve a list of keys

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
Request

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

Query Parameters

  • The number of keys to retrieve. By default, GET /keys returns the first 2000 keys. To retrieve a different set of keys, use limit with offset to page through your available resources. The maximum value for limit is 5000.

    Usage: If you have 20 keys in your instance, and you want to retrieve only the first 5 keys, use ../keys?limit=5.

    Constraints: 1 ≤ value ≤ 5000

    Default: 2000

  • 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=50.

    Constraints: value ≥ 0

    Default: 0

Response

Status Code

  • The list of keys was successfully retrieved.

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Retrieve the number of keys

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
Request

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

Response

Status Code

  • The metadata was successfully retrieved.

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Retrieve a key by ID

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

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

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

Path Parameters

  • The v4 UUID that uniquely identifies the key.

Response

Status Code

  • The key was successfully retrieved.

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

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

  • Your IBM Cloud access token is not authorized to access this resource.

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

  • Too many requests. Please wait a few minutes and try again.

  • 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

Invoke an action on a key

Invokes an action, such as a wrap, unwrap, or rotate operation, on a specified root 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 in the response. Use the latest ciphertext for future unwrap operations.

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

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

  • 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

  • The root key that is used as the wrapping key. It must be a v4 UUID for an active key.

Query Parameters

  • The action to perform on the specified key.

    Allowable values: [wrap,unwrap,rotate]

The request to perform a key wrap operation.

Response

The base request for key actions.

Status Code

  • Successful key operation.

  • Successful key operation. Your key was successfully rotated.

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

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • The key could not be found.

  • The key is not in an active state, so any KeyAction will fail. Check the key's nonactiveStateReason to understand how to proceed.

  • The requested key was previously deleted and is no longer available. Please delete references to this key.

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

  • Too many requests. Please wait a few minutes and try again.

  • 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

Delete a key by ID

Deletes a key by specifying the ID of the key.

Important: When you delete a key, you permanently shred its contents and associated data. The action cannot be reversed.

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

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

  • 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

  • The v4 UUID that uniquely identifies the key.

Response

Status Code

  • The key was successfully deleted.

  • The key was deleted.

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

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • The key could not be found.

  • The requested key was previously deleted and is no longer available. Please delete references to this key.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Retrieve a list of policies

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

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

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

Path Parameters

  • The v4 UUID that uniquely identifies the key.

Response

Status Code

  • The policies resource was successfuly retrieved

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

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • The key could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Replace an existing policy

Replaces the policy that is associated with a specified key

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

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

  • 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

  • The v4 UUID that uniquely identifies the key.

The base request for creating a new policies resource.

Response

Status Code

  • The policy was successfully replaced.

  • The policy was updated.

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

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • The requested key was previously deleted and is no longer available. Please delete references to this key.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Create a new transport key

Creates a transport encryption key that you can use to encrypt and import root keys into the service.

When you call POST /lockers, Key Protect creates an RSA key-pair from its HSMs. The service stores the encrypted private key in your service instance, and then returns the public key in the response entity-body. You can create only one transport key per service instance.

POST /api/v2/lockers
Request

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

The base request to create a transport encryption key.

Response

The response for creating a transport encryption key.

Status Code

  • The transport encryption key was successfully created.

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • The key could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Retrieve transport key metadata

Retrieves the metadata about the transport encryption key that is associated with your service instance.

GET /api/v2/lockers
Request

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

Response

The response for creating a transport encryption key.

Status Code

  • The transport key metadata was successfully retrieved.

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • The key could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • 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

Retrieve a transport key by ID

Retrieves the transport encryption key with a timestamp, remaining retrieval count and an import token. The payload is the public key that you can use to encrypt your key material.

Note: This method will fail if maxAllowedRetrievals has been reached. Use GET /lockers/{id} to check remainingRetrievals. The default value is 1.

GET /api/v2/lockers/{id}
Request

Custom Headers

  • Your IBM Cloud access token.

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

  • The v4 UUID used to correlate and track transactions.

  • 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

  • The v4 UUID that uniquely identifies the key.

Response

Status Code

  • The transport encryption key was successfully retrieved.

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

  • Your IBM Cloud access token is not authorized to access this resource.

  • The key could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • 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