years
2017, 2026

lastupdated

2026-04-12

keywords

list keys, view keys, retrieve encryption key

subcollection

key-protect

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

Retrieving a list of {{site.data.keyword.keymanagementserviceshort}} keys

{: #view-keys}

{{site.data.keyword.keymanagementservicefull}} provides a centralized system to view, manage, and audit your encryption keys. Audit your keys and access restrictions to keys to help ensure the security of your resources. {: shortdesc}

While you can assign fine-grained access to a single key, the list keys API does not return keys with individual access permissions. In other words, it does not return keys that only you can access. However, calling this API returns the keys in key rings you have access to. If you have access to all keys in an instance, you see all keys. You can view keys with individual access permissions by following the instructions in Viewing fine-grain access keys through IAM. Alternatively, use the API to pass the specific key ID. {: important}

It is a good practice to audit your key configuration regularly:

Examine when keys were created and determine whether it's time to rotate the key.
Monitor API calls to {{site.data.keyword.keymanagementserviceshort}} with {{site.data.keyword.logs_full_notm}}.
Inspect which users have access to keys and if the level of access is appropriate.

For more information about auditing access to your resources, see Managing user access.

Viewing keys in the console

{: #view-keys-gui} {: ui}

If you prefer to inspect the keys in your service by using a graphical interface, you can use the {{site.data.keyword.keymanagementserviceshort}} dashboard.

After you create or import your existing keys into the service, complete the following steps to view your keys.

Log in to the {{site.data.keyword.cloud_notm}} console{: external}.
Go to Menu > Resource List to view a list of your resources.
From your {{site.data.keyword.cloud_notm}} resource list, select your provisioned instance of {{site.data.keyword.keymanagementserviceshort}}.
Click Keys to see a list of all keys in your service instance. You can filter keys by their Key states (for example, to show only keys in the Enabled state) or by their Key ring ID by using the drop-down lists. You can sort individual values such as Last rotated date. Use the search bar to search keys by their display name, key ID, and alias. The quickest way to find a key is to search by its key ID. You can customize the fields in the table by using the Settings button. By default, you can see:

Column	Description
Name	The display name that you gave to your key.
Key ID	A unique key ID that was assigned to your key by the {{site.data.keyword.keymanagementserviceshort}} service. You can use the ID value to make calls to the service with the {{site.data.keyword.keymanagementserviceshort}} API{: external}.
Key ring ID	The key ring that the keys are associated with. These states include Deactivated, Deleted, Disabled, and Enabled.
Last rotated	The date the last time the key was rotated.
Key alias	The key alias (or aliases) of the key.
Type	The key type of the key (either a Root key or a Standard key).
State	The key state of the key, one of Deactivated, Deleted, Disabled, or Enabled.
{: caption="Describes the Keys table." caption-side="bottom"}

Other available fields in the table include:

Last modified: indicating the last time that the key was changed in any way.
Created: the date that the key was created.
Deleted: showing whether a key is in a deleted state (awaiting purge) or not.
Imported: indicating whether the key was created by using key material that is supplied by the user.
Rotation policy: showing whether this key has a rotation policy that is attached to it.
Associated resources: shows whether the key is protecting any resources.

The search capability is limited to a volume of 5,000 keys. If you have more than 5,000 keys and cannot filter the number to less than 5,000, your search fails unless it exactly matches a key ID or alias. For example, you can filter by key state to show only Enabled keys. For more information about the API spec for key search, see GET /keys. {: tip}

If you want to narrow the number of results returned by a search, try applying one or a combination of the following parameters:

not: when specified, inverts the logic that the search uses (for example, not:foo searches for keys that have aliases or names that do not contain foo).
escape: everything after this option is taken as plaintext (example: escape:not: searches for keys that have an alias or name that contains the substring not:).
exact: only looks for exact matches.
alias: only looks for key aliases.
name: only looks for key names.

not:exact:foobar looks for keys where key name or alias is not exactly foobar, while exact:not:foobar looks for keys where key name or alias is exactly not:foobar. {: note}

Search scopes behave in an OR manner. This means that when using more than one search scope, a match in at least one of the scopes results in the key being returned. By default (if no scopes are provided), the search is performed in both name and alias scopes. {: important}

Not seeing the full list of keys that are stored in your {{site.data.keyword.keymanagementserviceshort}} instance? Verify with your administrator that you are assigned in the correct role for the applicable {{site.data.keyword.keymanagementserviceshort}} instance or individual key. For more information about roles, see Roles and permissions.

Retrieving keys by state

{: #filter-key-state-gui} {: ui}

By filtering on the state of specific keys in your {{site.data.keyword.keymanagementserviceshort}} instance, you can retrieve keys that are in the states that you specify.

For example, you might have keys in your {{site.data.keyword.keymanagementserviceshort}} instance that are in the active, suspended, and destroyed states, but you only want to retrieve keys in the active state when you look through a list of keys.

For more information on key states, see Key states and transitions. {: note}

After you create or import your existing keys into the service, you have two options to view your keys. The first option, View keys through the resource list, works for all keys except those with fine-grained access. For information about viewing keys with fine-grain access, see Viewing fine-grain access keys IAM.

Viewing keys through the resource list

{: #filter-key-state-gui-resource-list} {: ui}

Log in to the {{site.data.keyword.cloud_notm}} console{: external}.
Go to Menu > Resource List to view a list of your resources.
From your {{site.data.keyword.cloud_notm}} resource list, select your provisioned instance of {{site.data.keyword.keymanagementserviceshort}}.
On the application details page, click the filter icon and select the dropdown from the Status menu.
Select the key state of the keys that you would like to retrieve.
Click the Apply button.
Further, in the table row headings, you can click on Last Updated to sort the list by the date that the keys in the table were updated most recently, or click on Type to list all of the root keys and standard keys as groups.

Viewing fine-grain access keys through IAM

{: #filter-key-state-gui-iam} {: ui}

From the menu bar, click Manage > Access (IAM), and select Users to browse the existing users in your account.
Select a table row, and click the ⋯ icon to open a list of options for that user. Then select Manage Access from the drop down list.
Here you can see all of the IAM information for this user, including the Access groups that they belong to. To specifically see the access policies for this user, click the Access policies tab.

An account owner or user with the appropriate privileges can see all of the policies that are assigned to this user, including any fine-grained access over keys.

Viewing keys with the API

{: #view-keys-api} {: api}

You can retrieve the contents of your keys by using the {{site.data.keyword.keymanagementserviceshort}} API.

Retrieving a list of keys

{: #retrieve-keys-api} {: api}

For a high-level view, you can browse keys that are managed in your provisioned instance of {{site.data.keyword.keymanagementserviceshort}} by making a GET call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys

{: codeblock}

Retrieve your authentication credentials to work with keys in the service.
View general characteristics about your keys by running the following curl command.
```
$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "x-kms-key-ring: <key_ring_ID>" \
    -H "correlation-id: <correlation_ID>"
```
{: codeblock}

Replace the variables in the example request according to the information in Table 1. For more information about optional parameters available when viewing collections of keys, including the ability to search your keys, see the API documentation regarding the List keys method.

Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your {{site.data.keyword.keymanagementserviceshort}} instance resides. For more information, see Regional service endpoints.
key_ID_or_alias	Required. The unique identifier or alias for the key that you want to inspect.
IAM_token	Required. Your {{site.data.keyword.cloud_notm}} 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.
instance_ID	Required. The unique identifier that is assigned to your {{site.data.keyword.keymanagementserviceshort}} service instance. For more information, see Retrieving an instance ID.
key_ring_ID	Optional. The unique identifier of the target key ring. If unspecified, the response includes all resources that the user has access to in the specified instance. If provided, the response includes only resources that the user has access to in the specified key ring. For more information, see Grouping keys.
correlation_ID	Optional. The unique identifier that is used to track and correlate transactions.
{: caption="Table 1. Variables needed to view keys with the {{site.data.keyword.keymanagementserviceshort}} API" caption-side="bottom"}

A successful GET api/v2/keys request returns a collection of keys that are available in your {{site.data.keyword.keymanagementserviceshort}} service instance.

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Root-key",
            "state": 1,
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "createdBy": "...",
            "creationDate": "2020-03-11T16:30:06Z",
            "lastUpdateDate": "2020-03-11T16:30:06Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": false,
            "imported": true,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        },
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Standard-key",
            "state": 1,
            "expirationDate": "2020-03-14T03:50:12Z",
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "createdBy": "...",
            "creationDate": "2020-03-12T03:50:12Z",
            "lastUpdateDate": "2020-03-12T03:50:12Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": true,
            "imported": false,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        }
    ]
}

{: screen}

By default, GET api/v2/keys returns your first 200 keys, but you can adjust this limit by using the limit parameter at query time. To learn more about limit and offset, see Retrieving a subset of keys.

Not seeing the full list of keys? You might need to use limit and offset or check with your administrator to help ensure you're assigned to the correct level access to keys in your instance. To learn more, see Unable to view or list keys. {: tip}

Retrieving a subset of keys

{: #retrieve-subset-keys-api} {: api}

By specifying the limit and offset parameters at query time, you can retrieve a subset of your keys, starting with the offset value that you specify.

For example, you might have 3000 total keys that are stored in your {{site.data.keyword.keymanagementserviceshort}} instance, but you want to retrieve keys 200 - 300 when you make a GET /keys request.

You can use the following example request to retrieve a different set of keys.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?offset=<offset>&limit=<limit>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

{: codeblock}

Replace the limit and offset variables in your request according to the following table.

Variable	Description
offset	The number of keys to skip. For example, if you have 50 keys in your instance and you want to list keys 26 - 50, use `../keys?offset=25`. You can also pair offset with limit to page through your available resources.
limit	The number of keys to retrieve. For example, if you have 100 keys in your instance and you want to list only 10 keys, use `../keys?limit=10`. The maximum value for limit is 5000.
{: caption="Table 2. Usage of the limit and offset variables" caption-side="bottom"}

Offset is the location of a particular key in a data set. The offset value is zero-based, which means that the 10th encryption key in a data set is at offset 9. {: tip}

Retrieving keys by state

{: #filter-keys-state-api} {: api}

By specifying the state parameter at query time, you can retrieve keys that are in the states that you specify.

The state query parameter takes in a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. For more information on key states, see Key states and transitions. {: note}

You can use the following example request to retrieve a different set of keys.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?state=<state_integers>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

{: codeblock}

Replace the state variable in your request according to the following table.

Variable	Description
state	The states of the keys to be retrieved. States are integers where Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5. For example, if you want to list only keys in the active state in your {{site.data.keyword.keymanagementserviceshort}} instance, use `../keys?state=1`. You can also pair states with offsets and limits to page through your available resources.
{: caption="Table 3. The state variable" caption-side="bottom"}

For usage notes, check out the following examples for setting your state query parameter.

URL	Description
`.../keys`	Lists all of your available resources, up to the first 200 keys.
`.../keys?state=5`	Lists keys in the deleted state.
`.../keys?state=2,3`	Lists keys in the suspended and deactivated state.
{: caption="Table 4. Usage notes for the state query parameter" caption-side="bottom"}

Retrieving keys by Extractable value

{: #filter-keys-extractable-state-api} {: api}

By specifying the extractable parameter at query time, you can retrieve keys whose material can leave the service.

For example, you might have both standard and root keys in your {{site.data.keyword.keymanagementserviceshort}} instance, but you only want to retrieve keys with extractable key material when you make a GET /keys request.

The extractable query parameter takes in a boolean. {: note}

You can use the following example request to retrieve a different set of keys.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?extractable=<extractable>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

{: codeblock}

Replace the extractable variable in your request according to the following table.

Variable Description

extractable The type of keys to be retrieved. Filters keys based on the extractable property. You can use this query parameter to search for keys whose material can leave the service. If set to true, standard keys are retrieved. If set to false, root keys are retrieved. If omitted, both root and standard keys are retrieved. For example, if you want to list only keys with extractable material in your {{site.data.keyword.keymanagementserviceshort}} instance, use ../keys?extractable=true. You can also pair extractable with offset, limit, and state to page through your available resources.

{: caption="Table 5. The extractable variable" caption-side="bottom"}

Variable	Description
extractable	The type of keys to be retrieved. Filters keys based on the extractable property. You can use this query parameter to search for keys whose material can leave the service. If set to `true`, standard keys are retrieved. If set to `false`, root keys are retrieved. If omitted, both root and standard keys are retrieved. For example, if you want to list only keys with extractable material in your {{site.data.keyword.keymanagementserviceshort}} instance, use `../keys?extractable=true`. You can also pair extractable with `offset`, `limit`, and `state` to page through your available resources.
{: caption="Table 5. The extractable variable" caption-side="bottom"}

For usage notes, check out the following examples for setting your extractable query parameter.

URL	Description
`../keys`	Lists all of your available resources, up to the first 200 keys.
`../keys?extractable=true`	Lists standard keys.
`../keys?extractable=false`	Lists root keys.
{: caption="Table 6. Usage notes for the extractable query parameter" caption-side="bottom"}

Sorting a list of keys

{: #filter-keys-sort-api} {: api}

Using the sort parameter in the query string sorts the list of keys returned based on one or more key properties. To sort on a property in descending order, prefix the term with "-". To sort on multiple key properties, use a comma to separate each property. The first property in the comma-separated list is evaluated before the next.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?sort=<sort-value>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

{: codeblock}

Variable	Description
sort-value	The list of properties for sorting. The key properties that can be sorted currently are: `id`, `state`, `extractable`, `imported`, `creationDate`, `lastUpdateDate`, `lastRotateDate`, `deletionDate`, `expirationDate`.
{: caption="Table 7. Usage notes for the sort query parameter" caption-side="bottom"}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Retrieving a list of {{site.data.keyword.keymanagementserviceshort}} keys

Viewing keys in the console

Retrieving keys by state

Viewing keys through the resource list

Viewing fine-grain access keys through IAM

Viewing keys with the API

Retrieving a list of keys

Retrieving a subset of keys

Retrieving keys by state

Retrieving keys by Extractable value

Sorting a list of keys

FilesExpand file tree

view-keys.md

Latest commit

History

view-keys.md

File metadata and controls

Retrieving a list of {{site.data.keyword.keymanagementserviceshort}} keys

Viewing keys in the console

Retrieving keys by state

Viewing keys through the resource list

Viewing fine-grain access keys through IAM

Viewing keys with the API

Retrieving a list of keys

Retrieving a subset of keys

Retrieving keys by state

Retrieving keys by Extractable value

Sorting a list of keys