---
name: hs-crypto-uko-set-up-api
title: Setting up Unified Key Orchestrator API calls - Unified Key Orchestrator Plan
description: 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.
last-updated: 2026-06-16
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/hs-crypto?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Setting up Unified Key Orchestrator API calls - Unified Key Orchestrator Plan
{: #set-up-uko-api}


You can use [Unified Key Orchestrator API](https://cloud.ibm.com/apidocs/uko){: external} to create, retrieve, and destroy key templates, keys and keystores in the IBM Cloud® Hyper Protect Crypto Services for Unified Key Orchestrator.
{: shortdesc}


Setting up Unified Key Orchestrator API calls only applies to the Unified Key Orchestrator Plan.
{: note}

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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-envelope-encryption&format=markdown). You can also use the [key management service API](https://cloud.ibm.com/apidocs/hs-crypto){: external} to create internal IBM Cloud KMS keys and perform actions towards keys. 

## Retrieving your IBM Cloud credentials
{: #retrieve-uko-credentials}

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

1. [Generate an IBM Cloud IAM access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown).

2. [Retrieve the instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown) that uniquely identifies your Hyper Protect Crypto Services instance.

## Forming your Unified Key Orchestrator API request
{: #form-uko-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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions&format=markdown) 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>.ep11.<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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions&format=markdown#new-service-endpoints).
{: note}
 



```cURL 
curl --location --request GET 'https://<instance_ID>.uko.<region>.hs-crypto.appdomain.cloud/api/v4/managed_keys' \
    --header 'Authorization: Bearer <access_token>' \ 
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \ 
    --header 'UKO-Vault: <vault_id>'
```
{: codeblock}

* Replace `<region>` and `<instance_ID>` with the region and port number of your API endpoint. You can get the `<region>` and `<instance_ID>` in your provisioned service instance UI dashboard through **Overview** &gt; **Unified Key Orchestrator endpoint URL**. Or, you can dynamically [retrieve the API endpoint URL](https://cloud.ibm.com/apidocs/uko#endpoint-urls){: external}. 

    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.
{: tip}


## What's next
{: #set-up-uko-api-next-steps}

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](https://cloud.ibm.com/apidocs/uko){: external}.