Managing your keys with the key management service API

Retrieving your IBM Cloud credentials

To work with the API, you need to generate your service and authentication credentials. To gather your credentials:

1. Generate an IBM Cloud IAM access token.
2. Retrieve the instance ID that uniquely identifies your Hyper Protect Crypto Services service instance.

Forming your key management service API request

When you make an API call to the service, structure your API request according to how you initially provisioned your instance of Hyper Protect Crypto Services.

To build your request, pair a regional service endpoint with the appropriate authentication credentials. For example, if you created a service instance for the us-south region, use the following endpoint and API headers to browse keys in your service:

If you create your instances after April 12 2024 in certain regions, you might need to use the new API endpoints with the new format as <INSTANCE_ID>.api.<REGION>.hs-crypto.appdomain.cloud. The availability date varies by region. For more information about the supported regions, the availability dates, and the new endpoint URLs, see New endpoints.

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

• Replace <port> with the port number of your API endpoint. You can get the <port> in your provisioned service instance dashboard through Overview > Key management endpoint URL. Or, you can dynamically retrieve the API endpoint URL.

  Note that the port range of a Hyper Protect Crypto Services instance is between 8000 - 19999.

  The returned value includes:

  {
    "instance_id": "<instance_ID>",
    "kms": {
      "public": "api.<region>.hs-crypto.cloud.ibm.com:<port>",
      "private":"api.private.<region>.hs-crypto.cloud.ibm.com:<port>"
    },
      "ep11": {
      "public": "ep11.<region>.hs-crypto.cloud.ibm.com:<port>",
      "private":"ep11.private.<region>.hs-crypto.cloud.ibm.com:<port>"
    }
  }
  

  For the key management service, use the <region> and <port> in the kms section.

• Replace <access_token> and <instance_ID> with your retrieved service and authentication credentials.

Want to track your API requests in case something goes wrong? When you include the -v flag as part of cURL request, you get a correlation-id value in the response headers. You can use this value to correlate and track the request for debugging purposes.

What's next

You're all set to start managing your encryption keys and data. To find out more about programmatically managing your keys, check out the key management service API reference doc.