---
name: hs-crypto-view-key-versions
title: Viewing root key versions
description: IBM Cloud® Hyper Protect Crypto Services.
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.

# Viewing root key versions
{: #view-key-versions}

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}

View the versions that are associated with a root key by using
IBM Cloud® Hyper Protect Crypto Services.
{: shortdesc}

When you rotate a root key, Hyper Protect Crypto Services
creates a new version of the key. As a security admin, you can audit the
rotation history of a root key by viewing the key version history.

Key versions are available only for root keys. To learn more about how key
rotation works in Hyper Protect Crypto Services, check out
[Comparing your key rotation options](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-root-key-rotation-intro&format=markdown#compare-key-rotation-options).
{: note}

## Viewing root key versions with the key management service API
{: #view-key-versions-api}

For a high-level view, you can list the versions that are associated with a root
key by making a `GET` call to the following endpoint.

 

```
https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/{id}/versions
```
{: codeblock}

1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api&format=markdown).

2. Retrieve the ID of the root key that you want to inspect.

    The ID value is used to access detailed information about the key. You can
    find the ID for a key in your service instance by
    [retrieving a list of your keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-keys&format=markdown),
    or by accessing the UI.

3. Get a list of versions that are associated with the root key by running the following cURL command.

    ```sh
    curl -X GET \
      'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/versions' \
      -H 'accept: application/vnd.ibm.kms.key.version+json' \
      -H 'authorization: Bearer <IAM_token>' \
      -H 'x-kms-key-ring: <key_ring_ID>' \
      -H 'bluemix-instance: <instance_ID>'
    ```
    {: codeblock}

    Replace the variables in the example request according to the following table.

    | Variable | Description |
    | --- | --- |
    | `region` | **Required.** The region abbreviation, such as `us-south` or `eu-de`, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions&format=markdown#service-endpoints). |
    | `key_ID` | **Required.** The unique identifier for the key that you want to inspect. |
    | `IAM_token` | **Required.** Your IBM Cloud access token. Include the full contents of the `IAM` token, including the Bearer value, in the cURL request. For more information, see [Retrieving an access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown). |
    | `key_ring_ID` | **Optional.** The unique identifier of the key ring that the key belongs to. If unspecified, Hyper Protect Crypto Services will search for the key in every key ring that is associated with the specified instance. Therefore, it is suggested to specify the key ring ID for a more optimized request. \n \n Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default. For more information, see [Managing key rings](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-key-rings&format=markdown). |
    | `instance_ID` | **Required.** The unique identifier that is assigned to your Hyper Protect Crypto Services instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown). |
    {: caption="Describes the variables needed to list key versions with the API" caption-side="bottom"}

    A successful `GET api/v2/keys/<key_ID>/versions` response returns the list
    of versions that are associated with the root key. The following JSON object
    shows an example returned value.

    ```json
    {
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.key.version+json",
        "collectionTotal": 2
      },
      "resources": [
        {
          "id": "02fd6835-6001-4482-a892-13bd2085f75d",
          "creationDate": "2020-03-05T16:39:25Z"
        },
        {
          "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6",
          "creationDate": "2020-03-02T16:28:38Z"
        }
      ]
    }
    ```
    {: screen}

    The `resources` object lists each key version, along with the ID and
    creation date, in reverse chronological order.