---
name: hs-crypto-set-up-kms-api
title: Managing your keys with the key management service API
description: IBM Cloud® Hyper Protect Crypto Services provides a key management service API to store, retrieve, and generate encryption keys.
last-updated: 2026-07-01
---

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

# Managing your keys with the key management service API
{: #set-up-kms-api}

IBM Cloud® Hyper Protect Crypto Services is deprecated. As of 28 March 2026, you can't create new instances, and access to free instances will be removed. Existing premium plan instances are supported until 28 March 2027. Any instances that still exist on that date will be deleted.
{: deprecated}

IBM Cloud® Hyper Protect Crypto Services provides a [key management service API](https://cloud.ibm.com/apidocs/hs-crypto){: external} to store, retrieve, and generate encryption keys.
{: shortdesc}

## Retrieving your IBM Cloud credentials
{: #retrieve-kms-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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown).
2. [Retrieve the instance ID that uniquely identifies your Hyper Protect Crypto Services service instance](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown).

## Forming your key management service API request
{: #form-kms-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 -X GET \
    https://<INSTANCE_ID>.api.us-south.hs-crypto.appdomain.cloud/api/v2/keys \
    -H 'accept: application/vnd.ibm.collection+json' \
    -H 'authorization: Bearer <access_token>' \
    -H 'bluemix-instance: <instance_ID>'
```
{: codeblock}

* Replace `<port>` with the port number of your API endpoint. You can get the `<port>` in your provisioned service instance dashboard through **Overview** &gt; **Key management endpoint URL**. Or, you can dynamically [retrieve the API endpoint URL](https://cloud.ibm.com/apidocs/hs-crypto#getinstance){: external}. 
    
    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": "<instance_ID>.api.<region>.hs-crypto.appdomain.cloud",
        "private":"<instance_ID>.api.private.<region>.hs-crypto.appdomain.cloud"
      },
        "ep11": {
        "public": "<instance_ID>.ep11.<region>.hs-crypto.appdomain.cloud",
        "private":"<instance_ID>.ep11.private.<region>.hs-crypto.appdomain.cloud"
      }
    }
    ```
    {: screen}

    For the key management service, use the `<region>` and `<instance_ID>` 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.
{: tip}


## What's next
{: #set-up-kms-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 key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto){: external}.