--- name: key-protect-view-keys title: Retrieving a list of Key Protect keys description: IBM® Key Protect for IBM Cloud® 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. last-updated: 2026-07-16 --- # Retrieving a list of Key Protect keys {: #view-keys} IBM® Key Protect for IBM Cloud® 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grant-access-keys#grant-access-key-level), the [list keys API](https://cloud.ibm.com/apidocs/key-protect#getkeys) 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys&interface=ui#filter-key-state-gui-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 Key Protect with IBM Cloud Logs](https://cloud.ibm.com/docs/cloud-logs). - 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-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 Key Protect dashboard. [After you create or import your existing keys into the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-root-keys), complete the following steps to view your keys. 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. Click **Keys** to see a list of all keys in your service instance. You can manage the table view in the following ways: * **Filter keys** - Use the drop-down lists in the table filter panel to filter by **Key state** (for example, **Enabled**) or **Key ring ID**. * **Sort keys** - Click column headers to sort by values such as **Last rotated date**. * **Search keys** - Use the search bar to search by display name, key ID, or alias. To quickly find a specific key, search by its key ID. * **Customize columns** - Click the **Settings** button to select which columns to display. By default, the table displays the following columns: | 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 Key Protect service. You can use the ID value to make calls to the service with the [Key Protect API](https://cloud.ibm.com/apidocs/key-protect){: external}. | | Key ring ID | The [key ring](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grouping-keys) 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-key-alias) (or aliases) of the key. | | Type | The [key type](https://cloud.ibm.com/docs/key-protect?topic=key-protect-envelope-encryption#key-types) of the key (either a Root key or a Standard key). | | State | The [key state](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-states) 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](https://cloud.ibm.com/apidocs/key-protect#getkeys). {: 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 Key Protect instance?** Verify with your administrator that you are assigned in the correct role for the applicable Key Protect instance or individual key. For more information about roles, see [Roles and permissions](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-access#manage-access-roles). ### Retrieving keys by state {: #filter-key-state-gui} {: ui} By filtering on the state of specific keys in your Key Protect instance, you can retrieve keys that are in the states that you specify. For example, you might have keys in your Key Protect 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-states#key-transitions). {: note} [After you create or import your existing keys into the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-create-root-keys), you have two options to view your keys. The first option, [View keys through the resource list](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys&interface=ui#filter-key-state-gui-resource-list), works for all keys except those with [fine-grained access](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grant-access-keys#grant-access-key-level). For information about viewing keys with fine-grain access, see [Viewing fine-grain access keys IAM](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys&interface=ui#filter-key-state-gui-iam). #### Viewing keys through the resource list {: #filter-key-state-gui-resource-list} {: ui} 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** page, click the filter icon to open the filter panel. 5. From the **State** dropdown, select the key state of the keys that you would like to retrieve. 6. Click the **Apply** button. 7. 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} 1. From the menu bar, click **Manage** > **Access (IAM)**, and select **Users** to browse the existing users in your account. 2. 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. 3. 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 Key Protect 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 Key Protect by making a `GET` call to the following endpoint. ```plaintext https://.kms.cloud.ibm.com/api/v2/keys ``` {: 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. View general characteristics about your keys by running the following `curl` command. ```sh $ curl -X GET \ "https://.kms.cloud.ibm.com/api/v2/keys" \ -H "accept: application/vnd.ibm.collection+json" \ -H "authorization: Bearer " \ -H "bluemix-instance: " \ -H "x-kms-key-ring: " \ -H "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](https://cloud.ibm.com/apidocs/key-protect#getkeys). 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 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-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 Key Protect API" caption-side="bottom"} A successful `GET api/v2/keys` request returns a collection of keys that are available in your Key Protect service instance. ```json { "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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys&interface=api#retrieve-subset-keys-api). 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-unable-to-list-specific-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 Key Protect 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. ```sh $ curl -X GET \ "https://.kms.cloud.ibm.com/api/v2/keys?offset=&limit=" \ -H "accept: application/vnd.ibm.collection+json" \ -H "authorization: Bearer " \ -H "bluemix-instance: " ``` {: 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. For example, you might have keys in your Key Protect instance that are in the active, suspended, and destroyed states, but you only want to retrieve keys in the active state when you make a `GET /keys` request. 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-states#key-transitions). {: note} You can use the following example request to retrieve a different set of keys. ```sh $ curl -X GET \ "https://.kms.cloud.ibm.com/api/v2/keys?state=" \ -H "accept: application/vnd.ibm.collection+json" \ -H "authorization: Bearer " \ -H "bluemix-instance: " ``` {: 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 Key Protect 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 Key Protect 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. ```sh $ curl -X GET \ "https://.kms.cloud.ibm.com/api/v2/keys?extractable=" \ -H "accept: application/vnd.ibm.collection+json" \ -H "authorization: Bearer " \ -H "bluemix-instance: " ``` {: 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 Key Protect 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](https://cloud.ibm.com/apidocs/key-protect#kp-get-key-sort-api) 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. ```sh $ curl -X GET \ "https://.kms.cloud.ibm.com/api/v2/keys?sort=" \ -H "accept: application/vnd.ibm.collection+json" \ -H "authorization: Bearer " \ -H "bluemix-instance: " ``` {: 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"}