Skip to main contentlogoCreated with Sketch.
  • Start for free

    • Introduction

    Last updated: 2020-10-22

    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:

    1. Provision the service instance.
    2. 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/

    Frankfurt:

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

    Sydney:

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

    Washington DC:

      https://zcryptobroker-wdc.us-east.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>

    Tips:

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

    Sydney:

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

    Frankfurt:

      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>

    Tips:

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

    Sydney:

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

    Frankfurt:

      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>

    Tips:

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

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

    To retrieve your instance ID:

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

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

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

    Error handling

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

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

    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.

    For more information, see Retrieving a subset of keys.

    Methods

    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/
    • Frankfurt: https://zcryptobroker-de.eu-de.mybluemix.net/crypto_v2/
    • Sydney: https://zcryptobroker-syd.au-syd.mybluemix.net/crypto_v2/
    • Washington DC: https://zcryptobroker-wdc.us-east.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}

    Request

    Path Parameters

    • id
      string

      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 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 instance could not be found. Verify that the instance ID specified is valid.

    • 500

      IBM Cloud Hyper Protect Crypto Services 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.cloud.ibm.com:9372"
  },
  "ep11": {
    "public": "ep11.us-south.hs-crypto.cloud.ibm.com:9371",
    "private": "ep11.private.us-south.hs-crypto.cloud.ibm.com:9372"
  }
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Internal Server Error: IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Create a key

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

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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

    One of

    The base request for creating a new key.

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

$.ajax(settings).done(function (response) {
  console.log(response);
});
    • 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": "...",
    "extractable": False
    }
  ]
}

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

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

print(response.text)

    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 Hyper Protect Crypto Services. 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 Cloud Hyper Protect Crypto Services 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.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": false,
      "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
    }
  ]
}
    • {
  "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 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Conflict: The import token that was used to encrypt this key has reached its `maxAllowedRetrievals` or `expirationDate`, and it is no longer available for key operations. To create a new import token, use `POST /import_token`."
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Internal Server Error: IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    List keys

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

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

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

      Constraints: 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]

    • curl 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>",
  }
}

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

    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 Cloud Hyper Protect Crypto Services 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.key+json",
    "collectionTotal": 2
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 1,
      "extractable": true,
      "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,
      "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
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Retrieve key total

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

    HEAD /api/v2/keys

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    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]

    • 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 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 Hyper Protect Crypto Services. Learn more

    • 429

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

    • 500

      IBM Cloud Hyper Protect Crypto Services 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 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Retrieve a key

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

    GET /api/v2/keys/{id}

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

    • id
      string

      The v4 UUID that uniquely identifies the key.

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

    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 Hyper Protect Crypto Services. 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 Cloud Hyper Protect Crypto Services 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.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Standard-key",
      "description": "...",
      "state": 1,
      "extractable": true,
      "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": "..."
    }
  ]
}
    • {
  "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 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Not Found: The key could not be found. Verify that the key ID specified is valid."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Internal Server Error: IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Invoke an action on a key

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

    Notes:

    • 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.
    • Checking the integrity of the key contents using Additional authentication data (AAD) is not supported.
    POST /api/v2/keys/{id}

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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
      string

      The v4 UUID that uniquely identifies the key.

    Query Parameters

    • action
      string

      The action to perform on the specified key.

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

    Request Body

    One of

    The base request for key actions.

    Example: 
    • 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>"
  }'
    • curl -X POST   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=unwrap   -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 '{
    "ciphertext": "<encrypted_data_key>",
  }'
    • curl -X POST   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=unwrap   -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 '{
    "ciphertext": "<encrypted_data_key>",
  }'
    • curl -X POST   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=rotate   -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 '{
    "payload": "<new_key_material>"
  }'
    • 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);
});
    • 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

    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 Hyper Protect Crypto Services. 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 Cloud Hyper Protect Crypto Services 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": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=",
  "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScDRDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvempiYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZlcnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9",
  "keyVersion": {
    "id": "..."
  }
}
    • {
  "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,
      "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
    }
  ]
}
    • {
  "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 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "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 appropriate state, so the KeyAction has failed."
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Gone: The requested key was previously deleted and is no longer available. 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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Delete a key

    Deletes a key by specifying the ID of the key. By default, Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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}

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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
      string

      The v4 UUID that uniquely identifies the key.

    Query Parameters

    • force
      boolean

      If set to true, Hyper Protect Crypto Services 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, Hyper Protect Crypto Services cannot delete the key. Use GET keys/{id}/registrations to review registrations between the key and its associated cloud resources. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.

      Default: false

    • curl -X DELETE   https://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": "DELETE",
  "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/api/v2/keys/<key_ID>/policies"

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

    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 Hyper Protect Crypto Services. Learn more

    • 404

      The key could not be found.

    • 409

      The key could not be deleted because it is protecting one or more cloud resources that have a retention policy. Use GET /keys/{id}/registrations to learn which resources this key is associated with. A registration with ”preventKeyDeletion”: true indicates that the associated resource has a retention policy. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this 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 Cloud Hyper Protect Crypto Services 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.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Root-key",
      "description": "...",
      "state": 5,
      "extractable": false,
      "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": false,
      "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 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "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": "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Retrieve key metadata

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

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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

    • id
      string

      The v4 UUID that uniquely identifies the key.

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

    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.

    • 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 Hyper Protect Crypto Services. 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 Cloud Hyper Protect Crypto Services 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.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "...",
      "name": "Standard-key",
      "description": "...",
      "state": 1,
      "extractable": true,
      "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
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Bad Request: The key metadata could not be retrieved due to a malformed, invalid, or missing ID."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    List key versions

    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 registered cloud services that you associate with the key use the latest key version to wrap your data. Learn more

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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

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

      Constraints: 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.

      Constraints: value ≥ 0

      Default: 0

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

    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
    • {
  "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"
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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.'"
  ]
}
    • {
  "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.'"
  ]
}

    Set key policies

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

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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

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

    One of

    The base request for key policy create or update.

    Example: 
    • curl -X PUT   https://api.<region>.hs-crypto.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>
        }
      }
    ]
  }'
    • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'content-type: application/vnd.ibm.kms.policy+json'   -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
    {
      "type": "application/vnd.ibm.kms.policy+json",
      "dualAuthDelete": {
        "enabled": <true|false>
        }
      }
    ]
  }'
    • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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>
        }
      }
    ]
  }'
    • var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com/api/v2/keys/<key_ID>/policies",
  "method": "PUT",
  "headers": {
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "content-type": "application/vnd.ibm.kms.policy+json"
  },
  "processData": false,
  "data": {
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
      "type": "application/vnd.ibm.kms.policy+json",
      "rotation": {
        "interval_month": <rotation_interval>
        }
      }
    ]
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
    • import requests
import json

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

payload = {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
    "type": "application/vnd.ibm.kms.policy+json",
    "rotation": {
      "interval_month": <rotation_interval>
      }
    }
  ]
}

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

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

print(response.text)

    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 Hyper Protect Crypto Services. 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 Cloud Hyper Protect Crypto Services 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.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": "..."
    }
  ]
}
      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "dualAuthDelete": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}
      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "rotation": {
        "interval_month": 3
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Gone: The requested key was previously deleted and is no longer available. 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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    List key policies

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

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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

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

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

    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 Hyper Protect Crypto Services. Learn more

    • 404

      The key could not be found.

    • 429

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

    • 500

      IBM Cloud Hyper Protect Crypto Services 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.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": "..."
    }
  ]
}
      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "dualAuthDelete": {
        "enabled": "<true|false>"
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}
      {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "...",
      "crn": "...",
      "rotation": {
        "interval_month": 3
      },
      "createdBy": "...",
      "creationDate": "...",
      "updatedBy": "...",
      "lastUpdateDate": "..."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "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": "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Set instance policies

    Creates or updates one or more policies for the specified service instance. Note: When you set an instance policy, Hyper Protect Crypto Services 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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services 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: [dualAuthDelete]

    Request Body

    One of

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

    Example: 
    • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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": 1
    },
    "resources": [
      {
        "policy_type": "dualAuthDelete",
        "policy_data": {
          "enabled": <true|false>
        }
      }
    ]
  }'
    • curl -X PUT   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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>
        }
      }
    ]
  }'

    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 Hyper Protect Crypto Services. 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 Cloud Hyper Protect Crypto Services 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 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Gone: The requested key was previously deleted and is no longer available. 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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    List instance policies

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

    GET /api/v2/instance/policies

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services 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: [dualAuthDelete]

    • curl GET   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/policies   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'accept: application/vnd.ibm.kms.policy+json'
    • curl GET   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/policies?policy=dualAuthDelete   -H 'authorization: Bearer <IAM_token>'   -H 'bluemix-instance: <instance_ID>'   -H 'accept: application/vnd.ibm.kms.policy+json'

    Response

    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 Hyper Protect Crypto Services. Learn more

    • 404

      The key could not be found.

    • 429

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

    • 500

      IBM Cloud Hyper Protect Crypto Services 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 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "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": "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Create an import token

    Creates an import token that you can use to encrypt and import root keys into the service. Learn more When you call POST /import_token, Hyper Protect Crypto Services 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 at a time.

    POST /api/v2/import_token

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Request Body

    ImportToken

    The base request to create an import token.

    • curl -X POST   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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>
  }'
    • var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/import_token",
  "method": "POST",
  "headers": {
    "accept": "application/vnd.ibm.collection+json",
    "authorization": "Bearer <IAM_token>",
    "bluemix-instance": "<instance_ID>",
    "content-type": "application/json"
  },
  "processData": false,
  "data": {
    "expiration": <expiration_time>,
    "maxAllowedRetrievals": <use_count>
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
    • import requests
import json

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

payload = {
  "expiration": <expiration_time>,
  "maxAllowedRetrievals": <use_count>
  }

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

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

print(response.text)

    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 Hyper Protect Crypto Services. Learn more

    • 429

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

    • 500

      IBM Cloud Hyper Protect Crypto Services 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
    • {
  "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "expirationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "maxAllowedRetrievals": 10,
  "remainingRetrievals": 10
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Retrieve an import token

    Retrieves the import token that is associated with your service instance. When you call GET /import_token, Hyper Protect Crypto Services 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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

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

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

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

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

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

print(response.text)

    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 Hyper Protect Crypto Services. 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 Cloud Hyper Protect Crypto Services 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
    • {
  "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "expirationDate": "YYYY-MM-DDTHH:MM:SSZ",
  "maxAllowedRetrievals": 10,
  "remainingRetrievals": 9,
  "payload": "...",
  "nonce": "..."
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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 Hyper Protect Crypto Services. [Learn more](https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-integrate-services#grant-access)'"
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Not found: An import token was not found in the specified service instance. To create an import token, use `POST /import_token`"
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Conflict: The import token has reached its `maxAllowedRetrievals` or `expirationDate`. To create a new import token, use `POST /import_token`."
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and try again."
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Internal Server Error: IBM Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Create a registration

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

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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

    • id
      string

      The v4 UUID that uniquely identifies the key.

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

    Example: 
    • curl -X POST   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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 Hyper Protect Crypto Services 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 Cloud Hyper Protect Crypto Services 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.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"
      }
    }
  ]
}
    • {
  "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/hs-crypto",
        "target": {
          "type": "param",
          "name": "urlEncodedResourceCRN"
        }
      }
    ]
  }
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Update a registration

    Service to service calls only. Updates an existing registration based on the properties that you specify. When you call PATCH /registrations, Hyper Protect Crypto Services 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}

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

    • id
      string

      The v4 UUID that uniquely identifies the key.

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

    UpdateRegistration

    The base request for updating a registration.

    Example: 
    • curl -X PATCH   https://api.<region>.hs-crypto.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 Hyper Protect Crypto Services 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 Cloud Hyper Protect Crypto Services 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.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"
      }
    }
  ]
}
    • {
  "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/hs-crypto",
        "target": {
          "type": "param",
          "name": "urlEncodedResourceCRN"
        }
      }
    ]
  }
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Replace a registration

    Service to service calls only. Replace an existing registration between a root key and a cloud resource. The key is identified by its ID, and the cloud resource is identified by its cloud resource name (CRN). When you call PUT /registrations, Hyper Protect Crypto Services replaces the existing registration with the properties that you provide in the request entity-body.

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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

    • id
      string

      The v4 UUID that uniquely identifies the key.

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

    ReplaceRegistration

    The base request for replacing a registration.

    Example: 
    • curl -X PUT   https://api.<region>.hs-crypto.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 Hyper Protect Crypto Services 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 Cloud Hyper Protect Crypto Services 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.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"
      }
    }
  ]
}
    • {
  "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/hs-crypto",
        "target": {
          "type": "param",
          "name": "urlEncodedResourceCRN"
        }
      }
    ]
  }
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Delete a registration

    Service to service calls only. Deletes an existing registration between a root key and a cloud resource. This action permanently removes the registration from the Hyper Protect Crypto Services database.

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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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
      string

      The v4 UUID that uniquely identifies the key.

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

    • curl -X DELETE   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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 Hyper Protect Crypto Services 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 Cloud Hyper Protect Crypto Services 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.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"
      }
    }
  ]
}
    • {
  "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/hs-crypto",
          "target": {
            "type": "param",
            "name": "urlEncodedResourceCRN"
          }
        }
      ]
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    List registrations for a key

    Retrieves a list of registrations that are associated with a specified root key. When you use a root key to protect an IBM Cloud resource, such as a Cloud Object Storage bucket, Hyper Protect Crypto Services 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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Path Parameters

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

      Constraints: 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.

      Constraints: 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.

    • curl -X GET   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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 Hyper Protect Crypto Services 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 Cloud Hyper Protect Crypto Services 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.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"
      }
    }
  ]
}
    • {
  "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/hs-crypto",
        "target": {
          "type": "param",
          "name": "urlEncodedResourceCRNQuery"
        }
      }
    ]
  }
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "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/hs-crypto"
      }
    ]
  }
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    List registrations for any key

    Retrieves a list of registrations that match the Cloud Resource Name (CRN) query that you specify. When you use a root key to protect an IBM Cloud resource, such as a Cloud Object Storage bucket, Hyper Protect Crypto Services creates a registration between the resource and root key. You can use GET /keys/{id}/registrations to understand which cloud resources are protected by keys in your Hyper Protect Crypto Services instance.

    GET /api/v2/keys/registrations

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    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 Hyper Protect Crypto Services 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 5000. 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.

      Constraints: 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.

      Constraints: 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.

    • curl -X GET   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/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 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 Hyper Protect Crypto Services 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 Cloud Hyper Protect Crypto Services 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.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"
      }
    }
  ]
}
    • {
  "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/hs-crypto",
        "target": {
          "type": "param",
          "name": "urlEncodedResourceCRNQuery"
        }
      }
    ]
  }
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "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 Cloud Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Please try again later.'"
  ]
}

    Acknowledge key events

    Service to service calls only. Acknowledges a key lifecycle event. When a customer performs an action on a root key, Hyper Protect Crypto Services 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

    Request

    Custom Headers

    • Bluemix-Instance
      string

      The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.

    • Correlation-Id
      string

      The v4 UUID used to correlate and track transactions.

    Request Body

    EventAcknowledge

    The base request for acknowledging a key action events.

    Example: 
    • curl -X POST   https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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 can 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
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Event acknowledgement can 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/hs-crypto",
          "target": {
            "type": "field",
            "name": "timestamp"
          }
        }
      ]
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    "errorMsg: 'Unauthorized: 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.'"
  ]
}
    • {
  "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/hs-crypto"
        }
      ]
    }
  ]
}
    • {
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.error+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "errorMsg": "Too Many Requests: Please wait a few minutes and tryagain."
    }
  ]
}