Retrieving key metadata

You can retrieve the general characteristics of a single encryption key by using IBM® Key Protect for IBM Cloud®.

While you can assign fine-grained access to a single key, note that calling the list keys API will not return keys that you have assigned individual access to (that only you can access, in other words). Calling this API will however return the keys in key rings you have access to (if you have access to all of the keys in an instance, you will see all keys). You can, however, see the keys that only you have access to by following the instructions in Granting access to keys to view the key through IAM or by using the API to pass the specific key ID.

Retrieving a key requires a Writer or Manager access policy, but you might need a way to view only the details about a key, such as its transition history or configuration, without retrieving the key itself. If you have Reader acces permissions, you can use the Key Protect API to retrieve only metadata about a key.

Viewing key metadata with the API

To view detailed information about a specific key, you can make a GET call to the following endpoint.

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

Retrieve your authentication credentials to work with keys in the service.
Retrieve the ID of the key that you would like 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, or by accessing the Key Protect dashboard.

Get details about the key by running the following curl command.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/metadata" \
    -H "accept: application/vnd.ibm.kms.key+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "x-kms-key-ring: <key_ring_ID>" \
    -H "correlation-id: <correlation_ID>"

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

Table 1. Describes the variables that are needed to view a details about a key with the Key Protect API.
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.
keyID_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.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.
key_ring_ID	Optional. The unique identifier of the key ring that the key is a part of. The header itself is optional, but if unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is recommended to specify the key ring ID for a more optimized request. Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default. For more information, see Grouping keys.
correlation_ID	Optional.The unique identifier that is used to track and correlate transactions.

A successful GET api/v2/keys/<key_ID_or_alias>/metadata response returns details about your key. The following JSON object shows an example returned value for a standard key.

{
		"metadata": {
				"collectionType": "application/vnd.ibm.kms.key+json",
				"collectionTotal": 1
		},
		"resources": [
				{
						"type": "application/vnd.ibm.kms.key+json",
						"id": "02fd6835-6001-4482-a892-13bd2085f75d",
						"name": "test-standard-key",
						"aliases": [
								"alias-1",
								"alias-2"
						],
						"state": 1,
						"expirationDate": "2020-03-15T03:50:12Z",
						"extractable": true,
						"crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
						"imported": false,
						"creationDate": "2020-03-12T03:50:12Z",
						"createdBy": "...",
						"algorithmType": "Deprecated",
						"algorithmMetadata": {
								"bitLength": "256",
								"mode": "Deprecated"
						},
						"algorithmBitSize": 256,
						"algorithmMode": "Deprecated",
						"lastUpdateDate": "2020-03-12T03:50:12Z",
						"dualAuthDelete": {
								"enabled": false
						},
						"deleted": false
				}
		]
}

Next steps

Need to retrieve the payload value for a standard key? To learn more, see Retrieving a key.

For a detailed description of the response parameters, see the Key Protect REST API reference doc.