---
name: key-protect-view-key-versions
title: Viewing key versions
description: View the versions that are associated with a root key by using IBM® Key Protect for IBM Cloud®.
last-updated: 2026-06-24
---

{:shortdesc: .shortdesc}
{:screen: .screen}
{:pre: .pre}
{:table: .aria-labeledby="caption"}
{:external: target="_blank" .external}
{:codeblock: .codeblock}
{:tip: .tip}
{:note: .note}
{:important: .important}
{:preview: .preview}
{:term: .term}
{:ui: .ph data-hd-interface='ui'}
{:api: .ph data-hd-interface='api'}

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

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

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

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

## How many key versions do you have?
{: #view-key-versions-ui}
{: ui}

To see how many versions you have of each key you have deployed:

1. [Log in to the IBM Cloud console](https://cloud.ibm.com/login/){: external}.

2. Go to **Menu** > **Resource List** to view a list of your resources.

3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.

4. On the **Keys** panel, click the ⋯ icon and select **Details**. This opens a side panel that shows, among other things, the number of versions of this key you have.

5. If you want to know how many key versions you have in your instance, you must repeat this process for every key in your instance. Note that because only root keys can be rotated, all of your standard keys have only one version.

## Viewing key versions with the API
{: #view-key-versions-api}
{: 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.

```plaintext
https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/versions
```
{: codeblock}

1. [Retrieve your authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).

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
    Key Protect instance by
    [retrieving a list of your keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys),
    or by accessing the Key Protect
    dashboard.

3. Get a list of versions that are associated with the root key by running the following `curl` command.
    
    You can add a query parameter, `?totalCount=true`, as shown. This parameter returns `totalCount` in the response metadata for use with pagination.

    ```sh
    $ curl -X GET \
        "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/versions?totalCount=<show_total>&allKeyStates=<work_for_keys_in_any_state>" \
        -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-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions#service-endpoints). |
key_ID_or_alias | **Required**. The unique identifier or alias 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/key-protect?topic=key-protect-retrieve-access-token). |
instance_ID | **Required**. The unique identifier that is assigned to your Key Protect service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). |
key_ring_ID | **Optional**. The unique identifier of the key ring that the key is a part of. If unspecified, Key Protect searches for the key in every key ring that is associated with the specified instance. Specifying the key ring ID is recommended for a more optimized request. The key ring ID of keys that are created without an `x-kms-key-ring` header is `default`. For more information, see [Grouping keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grouping-keys). |
show_total | **Optional**. If set to `true`, returns `totalCount` in the response metadata for use with pagination for all keys in an active state, unless `allKeyStates` is also set to `true`. The `totalCount` value returned specifies the total number of key versions that match the request, disregarding limit and offset. The default is set to `false`. |
allKeyStates | **Optional**. If not set to `true`, an HTTP 409 is returned for all non-active keys. |
{: caption="Table 1. Variables needed to list key versions with the Key Protect API" caption-side="bottom"}

A successful `GET api/v2/keys/<keyID_or_alias>/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 its ID and
creation date, in reverse chronological order.