Setting up Unified Key Orchestrator API calls - Unified Key Orchestrator Plan

You can use Unified Key Orchestrator API to create, retrieve, and destroy key templates, keys and keystores in the IBM Cloud® Hyper Protect Crypto Services for Unified Key Orchestrator.

Setting up Unified Key Orchestrator API calls only applies to the Unified Key Orchestrator Plan.

When you use the Unified Key Orchestrator API to create IBM Cloud KMS keys that are installed in internal KMS keystores, these keys are root keys and can be used for envelope encryption. You can also use the key management service API to create internal IBM Cloud KMS keys and perform actions towards keys.

Retrieving your IBM Cloud credentials

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

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

Forming your Unified Key Orchestrator 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>.uko.<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 --location --request GET 'https://uko.<region>.hs-crypto.cloud.ibm.com:<port>/api/v4/managed_keys' \
    --header 'Authorization: Bearer <access_token>' \ 
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \ 
    --header 'UKO-Vault: <vault_id>'

Replace <region> and <port> with the region and port number of your API endpoint. You can get the <region> and <port> in your provisioned service instance UI dashboard through Overview > Unified Key Orchestrator 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.
Replace <access_token> with your retrieved service and authentication credentials.
Replace <vault_id> with the ID of the vault that your keys are assigned to.

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 Unified Key Orchestrator API reference doc.