IBM Cloud Hyper Protect Crypto Services API

Introduction

IBM Cloud Hyper Protect Crypto Services is a dedicated key management service and hardware security module (HSM). It is designed to enable you to take control of your cloud data encryption keys and cloud hardware security models, and is the only service in the industry built on FIPS 140-2 Level 4-certified hardware. Hyper Protect Crypto Services is integrated with the IBM® Key Protect for IBM Cloud™ REST API, so that you can store, retrieve, and generate encryption keys.

You can try API requests directly on this site by clicking Try it out on the right pane. Before you use it, make sure to do the following:

Provision the service instance.
Initialize the service instance to take control of your master key.

By using the Try it out function, you make real-time API calls to the service instance that you provision and you are charged for any API calls that you make. For detailed pricing information, see Hyper Protect Crypto Services catalog page.

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

API endpoint

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. The endpoint varies depending on which regional service endpoint you are using:

Dallas:

  https://zcryptobroker.mybluemix.net/crypto_v2/

https://zcryptobroker.mybluemix.net/crypto_v2/

Sydney:

  https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/

https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/

Frankfurt:

  https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/

https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/

To call other API methods, use the following endpoint URL that is returned by calling the Retrieve the API endpoint URL method:

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

You need to call the Retrieve the API endpoint URL API first so as to retrieve the endpoint URL of the other APIs.
Replace <region> with the prefix that represents the geographic area where your service instance resides. For more information, see Regions and locations.
Replace <port> with the port number of the API endpoint.

API endpoint

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. The endpoint varies depending on which regional service endpoint you are using:

Dallas:

  https://zcryptobroker.mybluemix.net/crypto_v2/

https://zcryptobroker.mybluemix.net/crypto_v2/

Sydney:

  https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/

https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/

Frankfurt:

  https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/

https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/

To call other API methods, use the following endpoint URL that is returned by calling the Retrieve the API endpoint URL method:

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

You need to call the Retrieve the API endpoint URL API first so as to retrieve the endpoint URL of the other APIs.
Replace <region> with the prefix that represents the geographic area where your service instance resides. For more information, see Regions and locations.
Replace <port> with the port number of the API endpoint.

API endpoint

Use the Retrieve the API endpoint URL method first to retrieve the URL for the dedicated API endpoint for key management operations. The endpoint varies depending on which regional service endpoint you are using:

Dallas:

  https://zcryptobroker.mybluemix.net/crypto_v2/

https://zcryptobroker.mybluemix.net/crypto_v2/

Sydney:

  https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/

https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/

Frankfurt:

  https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/

https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/

To call other API methods, use the following endpoint URL that is returned by calling the Retrieve the API endpoint URL method:

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

https://api.<region>.hs-crypto.cloud.ibm.com:<port>

You need to call the Retrieve the API endpoint URL API first so as to retrieve the endpoint URL of the other APIs.
Replace <region> with the prefix that represents the geographic area where your service instance resides. For more information, see Regions and locations.
Replace <port> with the port number of the API endpoint.

Authentication

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

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. Alternatively, you can also retrieve an access token with the CLI. For more information, see Retrieving an access token.

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

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

Replace <API_KEY> with your service ID API key. For more information, see Retrieving an access token with the API. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

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);
});
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 ID API key. For more information, see Retrieving an access token with the API. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

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)
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 ID API key. For more information, see Retrieving an access token with the API. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access '{namespace}'.
`404`	Not Found	The requested resource could not be found.
`408`	Request Timeout	The connection to the server timed out. Wait a few minutes, then try again.
`409`	Conflict	The entity is already in the requested state.
`500`	Internal Server Error	offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Metadata

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

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

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

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.

Retrieve the API endpoint URL

Retrieves the URL for the dedicated API endpoint for key management operations on a Hyper Protect Crypto Services instance. The endpoint URL varies depending on which regional service endpoint you are using. Dallas: https://zcryptobroker.mybluemix.net/crypto_v2/; Sydney: https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/; Frankfurt: https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/. Depending on whether you are using public or private endpoint, choose the proper endpoint URL in the kms section returned for all API methods in this API reference doc.

GET /instances/{id}

/instances/{id}

Request

Custom Headers

Authorization
string
Your IBM Cloud access token.

Path Parameters

id
byte
The IBM Cloud UUID that uniquely identifies the instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.

```
curl -X GET \
  https://zcryptobroker.mybluemix.net/crypto_v2/instances/{id} \
  -H 'Authorization: Bearer {access_token}'
```

```
var settings = {
 "url": "https://zcryptobroker.mybluemix.net/crypto_v2/instances/{id}",
  "method": "GET",
  "headers": {
   'Authorization': 'Bearer {access_token}'
  }
}

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

```
import requests

url = 'https://zcryptobroker.mybluemix.net/crypto_v2/instances/{id}'

headers = {
'Authorization': 'Bearer {access_token}',
}

response = requests.request('GET', url, headers=headers)

print(response.text)
```

Response

Response Body

InstanceConnectionRead

Status Code

200
The instance connection info was successfully retrieved.
401
Your access token is invalid or does not have the necessary permissions to access this resource.
404
The instance could not be found. Verify that the instance ID specified is valid.
500
IBM Hyper Protect Crypto 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

{ "instance_id": "4ec51d44-d94d-4200-bc2c-fcfb04b1287c", "kms": { "public": "api.us-south.hs-crypto.cloud.ibm.com:9371", "private": "api.private.us-south.hs-crypto.ibm.com:9372" }, "ep11": { "public": "ep11.us-south.hs-crypto.cloud.ibm.com:9371", "private": "" } }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }

Create a new key

Creates a new key with specified key material. Hyper Protect Crypto 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

/api/v2/keys

Request

Custom Headers

Authorization
string
Your IBM Cloud access token.
Bluemix-Instance
byte
The IBM Cloud instance ID that identifies your Crypto service instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.
Correlation-Id
byte
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, Hyper Protect Crypto 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]

Request Body

CreateKeyCollection

The base request for creating a new key.

```
curl -X POST \
  https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'content-type: application/vnd.ibm.kms.key+json' \
  -H 'prefer: return=representation' \
  -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.key+json",
      "collectionTotal": 1
    },
    "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "Test key",
      "extractable": false
      }
    ]
  }'
```
curl -X POST \ https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys \ -H 'authorization: Bearer <IAM_token>' \ -H 'bluemix-instance: <instance_ID>' \ -H 'content-type: application/vnd.ibm.kms.key+json' \ -H 'prefer: return=representation' \ -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "Test key", "extractable": false } ] }'

Example request

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys",
  "method": "POST",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation",
    "content-type": "application/vnd.ibm.kms.key+json"
  },
  "processData": false,
  "data": {
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.key+json",
      "collectionTotal": 1
    },
    "resources": [
      {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "Test key",
      "extractable": false
      }
    ]
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys",
  "method": "POST",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation",
    "content-type": "application/vnd.ibm.kms.key+json"
  },
  "processData": false,
  "data": {
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.key+json",
      "collectionTotal": 1
    },
    "resources": [
      {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "Test key",
      "extractable": false
      }
    ]
  }
}

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

Example request

import requests
import json

url = "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys"

payload = {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
    "type": "application/vnd.ibm.kms.key+json",
    "name": "Root-key",
    "description": "Test key",
    "extractable": false
    }
  ]
}

headers = {
  "authorization": "Bearer <IAM_token>",
  "bluemix-instance": "<instance_ID>",
  "prefer": "return=representation",
  "content-type": "application/vnd.ibm.kms.key+json"
}

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

print(response.text)import requests
import json

url = "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys"

payload = {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
    "type": "application/vnd.ibm.kms.key+json",
    "name": "Root-key",
    "description": "Test key",
    "extractable": false
    }
  ]
}

headers = {
  "authorization": "Bearer <IAM_token>",
  "bluemix-instance": "<instance_ID>",
  "prefer": "return=representation",
  "content-type": "application/vnd.ibm.kms.key+json"
}

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

print(response.text)

Response

Response Body

CreateKeyCollection

Status Code

201
The key was successfully created.
400
The key is missing a required field.
401
Your access token is invalid or does not have the necessary permissions to access this resource.
403
The instance ID is malformed or invalid.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Hyper Protect Crypto 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",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": false,
      "crn": "..."
    }
  ]
}{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": false,
      "crn": "..."
    }
  ]
}

{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key is missing a required field." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }

Retrieve a list of keys

Retrieves a list of keys that are stored in your Hyper Protect Crypto 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

/api/v2/keys

Request

Custom Headers

Authorization
string
Your IBM Cloud access token.
Bluemix-Instance
byte
The IBM Cloud instance ID that identifies your Crypto service instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.
Correlation-Id
byte
The v4 UUID used to correlate and track transactions.

Query Parameters

limit
integer
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
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=50.

Constraints: value ≥ 0
Default: 0

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

```
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys",
  "method": "GET",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "content-type": "application/vnd.ibm.kms.key+json"
  }
}

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

```
import requests

url = "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys"

headers = {
  "authorization": "Bearer <IAM_token>",
  "bluemix-instance": "<instance_ID>",
  "accept": "application/vnd.ibm.kms.key+json",
}

response = requests.request('GET', url, headers=headers)

print(response.text)
```

Response

Response Body

ListKeyCollection

metadata
The metadata that describes the resource array.

resources

An array of resources.

Example:

{
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": false,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    }
  ]
}{
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": false,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    }
  ]
}

Status Code

200
The list of keys was successfully retrieved.
401
Your access token is invalid or does not have the necessary permissions to access this resource.
403
The instance ID is malformed or invalid.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Hyper Protect Crypto 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",
      "name": "Root-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": false,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    }
  ]
}{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": false,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    },
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "..."
    }
  ]
}

{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }

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

/api/v2/keys

Request

Custom Headers

Authorization
string
Your IBM Cloud access token.
Bluemix-Instance
byte
The IBM Cloud instance ID that identifies your Crypto service instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.
Correlation-Id
byte
The v4 UUID used to correlate and track transactions.

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

```
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys",
  "method": "HEAD",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>"
  }
}

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

```
import requests

url = "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys"

headers = {
  "authorization": "Bearer <IAM_token>",
  "bluemix-instance": "<instance_ID>",
  "accept": "application/vnd.ibm.kms.key+json",
}

response = requests.request('HEAD', url, headers=headers)

print(response.text)
```

Response

Status Code

200
The metadata was successfully retrieved.
401
Your access token is invalid or does not have the necessary permissions to access this resource.
403
The instance ID is malformed or invalid.
429
Too many requests. Please wait a few minutes and try again.
500
IBM Hyper Protect Crypto 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

{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }

Retrieve a key by ID

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

GET /api/v2/keys/{id}

/api/v2/keys/{id}

Request

Custom Headers

Authorization
string
Your IBM Cloud access token.
Bluemix-Instance
byte
The IBM Cloud instance ID that identifies your Crypto service instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.
Correlation-Id
byte
The v4 UUID used to correlate and track transactions.

Path Parameters

id
byte
The v4 UUID that uniquely identifies the key.

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

```
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>",
  "method": "GET",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>"
  }
}

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

```
import requests

url = 'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>'

headers = {
    'authorization': 'Bearer <IAM_token>',
    'bluemix-instance': '<instance_ID>',
    'accept': 'application/vnd.ibm.kms.key+json',
}

response = requests.request('GET', url, headers=headers)

print(response.text)
```

Response

Response Body

GetKeyCollection

metadata
The metadata that describes the resource array.

resources

An array of resources.

Example:

{
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "...",
      "payload": "..."
    }
  ]
}{
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "...",
      "payload": "..."
    }
  ]
}

Status Code

200
The key was successfully retrieved.
400
The key could not be retrieved due to a malformed, invalid, or missing ID.
401
Your access token is invalid or does not have the necessary permissions to access this resource.
403
The instance ID is malformed or invalid.
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 Hyper Protect Crypto 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",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "...",
      "payload": "..."
    }
  ]
}{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Standard-key",
      "id": "...",
      "description": "...",
      "state": 1,
      "extractable": true,
      "createdBy": "...",
      "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
      "crn": "...",
      "payload": "..."
    }
  ]
}

{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key could not be retrieved due to a malformed, invalid, or missing ID." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. Verify that the key ID specified is valid." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }

Invoke an action on a key

Invokes an action, such as a wrap, unwrap, or rotate operation, on a specified root key. Notes: 1. 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. 2. Checking the integrity of the key contents with additional authentication data (AAD) is not supported.

POST /api/v2/keys/{id}

/api/v2/keys/{id}

Request

Custom Headers

Authorization
string
Your IBM Cloud access token.
Bluemix-Instance
byte
The IBM Cloud instance ID that identifies your Crypto service instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.
Correlation-Id
byte
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, Hyper Protect Crypto 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
byte
The root key that is used as the wrapping key. It must be a v4 UUID for an active key.

Query Parameters

action
string
The action to perform on the specified key.

Allowable values: [wrap,unwrap,rotate]

Request Body

KeyAction

The request to perform a key wrap operation.

```
curl -X POST \
  https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=wrap \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'accept: application/vnd.ibm.kms.key_action+json' \
  -H 'content-type: application/vnd.ibm.kms.key_action+json' \
  -d '{
    "plaintext": "<data_key>"
  }'
```

Example request

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=wrap",
  "method": "POST",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation",
    "accept": "application/vnd.ibm.kms.key_action+json",
    "content-type": "application/vnd.ibm.kms.key_action+json"
  },
  "processData": false,
  "data": {
    "plaintext": "<data_key>"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=wrap",
  "method": "POST",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation",
    "accept": "application/vnd.ibm.kms.key_action+json",
    "content-type": "application/vnd.ibm.kms.key_action+json"
  },
  "processData": false,
  "data": {
    "plaintext": "<data_key>"
  }
}

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

Example request

import requests
import json

url = "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>"

querystring = {
  "action": "wrap"
  }

payload = {
  "plaintext": "string"
  }

headers = {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation",
    "accept": "application/vnd.ibm.kms.key_action+json",
    "content-type": "application/vnd.ibm.kms.key_action+json"
    }

response = requests.request("POST", url, data=json.dumps(payload), headers=headers, params=querystring)

print(response.text)import requests
import json

url = "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>"

querystring = {
  "action": "wrap"
  }

payload = {
  "plaintext": "string"
  }

headers = {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation",
    "accept": "application/vnd.ibm.kms.key_action+json",
    "content-type": "application/vnd.ibm.kms.key_action+json"
    }

response = requests.request("POST", url, data=json.dumps(payload), headers=headers, params=querystring)

print(response.text)

Response

Response Body

KeyAction

The base request for key actions.

Status Code

200
Successful key operation.
204
Successful key operation. Your key was successfully rotated.
400
Your authentication data or key is invalid, or the entity-body is missing a required field.
401
Your access token is invalid or does not have the necessary permissions to access this resource.
403
The instance ID is malformed or invalid.
404
The key could not be found.
409
The key is not in an active state, so any KeyAction will fail. Check the key's nonactiveStateReason to understand how to proceed.
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 Hyper Protect Crypto 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

{ "plaintext": "...", "ciphertext": "..." }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Bad Request: Your authentication data or key is invalid, or the entity-body is missing a required field.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Conflict: The key is not in an active state, so any KeyAction will fail. Check the key's nonactiveStateReason to understand how to proceed.'" ] }
{ "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.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unprocessable Entity: The ciphertext provided for the unwrap operation was not wrapped by this key.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }

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}

/api/v2/keys/{id}

Request

Custom Headers

Authorization
string
Your IBM Cloud access token.
Bluemix-Instance
byte
The IBM Cloud instance ID that identifies your Crypto service instance. For how to retrieve your instance ID, see Retrieving your instance ID for instructions.
Correlation-Id
byte
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, Hyper Protect Crypto 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
byte
The v4 UUID that uniquely identifies the key.

```
curl -X DELETE \
  https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID> \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'prefer: return=representation' \
  -H 'accept: application/vnd.ibm.kms.key+json'
```

```
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>",
  "method": "DELETE",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation"
  }
}

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

```
import requests

url = "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>"

headers = {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "prefer": "return=representation",
    "accept": "application/vnd.ibm.kms.key+json"
}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
```

Response

Response Body

DeleteKeyCollection

Status Code

200
The key was successfully deleted.
204
The key was deleted.
400
The key cannot be deleted due to a malformed, invalid, or missing ID.
401
Your access token is invalid or does not have the necessary permissions to access this resource.
403
The instance ID is malformed or invalid.
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 Hyper Protect Crypto 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",
      "name": "Root-key",
      "description": "...",
      "state": 5,
      "extractable": false,
      "crn": "...",
      "deleted": true,
      "deletionDate": "YYYY-MM-DDTHH:MM:SSZ",
      "deletedBy": "..."
    }
  ]
}{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "name": "Root-key",
      "description": "...",
      "state": 5,
      "extractable": false,
      "crn": "...",
      "deleted": true,
      "deletionDate": "YYYY-MM-DDTHH:MM:SSZ",
      "deletedBy": "..."
    }
  ]
}

{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key cannot be deleted due to a malformed, invalid, or missing ID." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Unauthorized: Your access token is invalid or does not have the necessary permissions to access this resource.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Forbidden: The instance ID is malformed or invalid." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found." } ] }
{ "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.'" ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Please wait a few minutes and try again." } ] }
{ "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ "errorMsg: 'Internal Server Error: IBM Hyper Protect Crypto is currently unavailable. Your request could not be processed. Please try again later.'" ] }

Introduction

Authentication

Error handling

Metadata

Pagination

Methods

Retrieve the API endpoint URL

Custom Headers

Authorization

Path Parameters

id

Response Body

instance_id

apiConnectionInfo

Status Code

200

401

404

500

Create a new key

Custom Headers

Authorization

Bluemix-Instance

Correlation-Id

Prefer

Request Body

metadata

resources

Response Body

metadata

resources

Status Code

201

400

401

403

429

500

Retrieve a list of keys

Custom Headers

Authorization

Bluemix-Instance

Correlation-Id

Query Parameters

limit

offset

Response Body

metadata

resources

Status Code

200

401

403

429

500

Retrieve the number of keys

Custom Headers

Authorization

Bluemix-Instance

Correlation-Id

Status Code

200

401

403

429

500

Retrieve a key by ID

Custom Headers

Authorization

Bluemix-Instance

Correlation-Id

Path Parameters

id

Response Body

metadata

resources

Status Code

200

400

401