vania-janet/multiturn-rag-retrieval-data huggingface dataset:
}

For a detailed description of the response parameters, see the Key Protect [REST API reference doc](https://cloud.ibm.com/apidocs/key-protect).

Each key can have up to five aliases. There is a limit of 1,000 aliases per instance.





 Deleting key aliases with the API 

Delete a key alias by making a DELETE call to the following endpoint.

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



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. Delete a key alias by running the following curl command.

$ curl -X DELETE "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/aliases/<key_alias>" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "correlation-id: <correlation_ID>"



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



Table 2. Describes the variables that are needed to delete a key alias with the Key Protect API

 Variable Description 

 region Required. The region abbreviation, such as us-southor eu-gb, that represents the geographic area where your Key Protect instance resides. <br> <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 keyID_or_alias Required.
<br> <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 keyID_or_alias Required. The unique identifier or alias for the root key that you used for the initial wrap request. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. <br> <br>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. <br> <br>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 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. <br> <br>Note: The key ring ID of keys that are created without an x-kms-key-ring header is: default. <br> <br>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. 
 additional_data Optional.The additional authentication data (AAD) that is used to further secure the key. Each string can hold up to 255 characters. If you supply AAD when you make a wrap call to the service, you must specify he same AAD during the unwrap call. 
 encrypted_data_key Required.
$ ibmcloud kp key rotate 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Rotating root key...
OK

 Inspect the versions
$ ibmcloud kp key versions 807eb0a6-cc10-4bfe-8331-41a6f712c4ea -n 12 -s 12 -o json
{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key.version+json",
"collectionTotal": 12
},
"resources": [
{
"id": "21562e93-8882-420e-90a7-912c70023373",
"creationDate": "2021-07-08T17:02:10Z"
},
{
"id": "390086ac-76fa-4094-8cf3-c0829bd69526",
"creationDate": "2021-08-08T17:02:40Z"
},...10x]
]
}

Show more





 Example 5 

An optional flag to return the number of versions of a key that is not currently active. Previously, the command would have failed, as in the following example:

 Attempt to show version count
$ ibmcloud kp key versions af61298c-d75d-42a8-aa76-e04178cf4685 -i 99980ccc-d482-4cd0-bb41-deb4f7f1eb92 -t

Retrieving key Versions...
FAILED
KEY_ACTION_INVALID_STATE_ERR
Key is not in a valid state
Correlation-ID:a494bf49-be82-426f-88d8-17b58cc8634d

With CLI version 0.8.0 and higher, the command succeeds when adding the -a flag, as in the following example:
If no key ring is selected, keys are placed in the default key ring. Note that to place the key you're creating in a key ring, you must have the Manager role over that key ring. For more information about roles, check out [Managing user access](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-access). 



When you are finished filling out the key's details, click Import key to confirm.

If you know which key ring you want a key to be placed in, and you are a Manager of that key ring, you can also navigate to the Key rings panel, select ⋯ and click Add key to key ring. This will open the same panel you see by clicking Add on the Keys page with the Key rings variable filled in with the name of the key ring.





 Importing standard keys 

Import a standard key by making a POST call to the following endpoint:

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



1. [Retrieve your service and authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).
2. Call the [Key Protect API](https://cloud.ibm.com/apidocs/key-protect) with the following curl command.

$ curl -X POST "https://<region>.kms.cloud.ibm.com/api/v2/keys" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "correlation-id: <correlation_ID>" -H "prefer: <return_preference>" -d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
must be done in the console user interface (UI) because
 there is no API or CLI support at this time

 capture the name of the COS bucket that was created
$ COS_BUCKET=my-cos-kms-bucket

 upload an object to COS
$ ibmcloud cos put-object --bucket $COS_BUCKET --key '/cos-file.txt' --body cos-file-upload.txt

 delete the authorization policy between COS AND KMS - this breaks everything
$ ibmcloud iam authorization-policy-delete $COS_KMS_AUTHORIZATION --force

 get the object from COS - this fails because COS no longer has access to KMS
$ ibmcloud cos get-object --bucket $COS_BUCKET --key '/cos-file.txt' cos-file-download.txt

FAILED
ServiceNotAuthorized: The specified COS Service Instance does not have sufficient
permissions to access the resource provided in the ibm-sse-kp-customer-root-key-crn request header
status code: 401,
request id: a51e1da3-9bf7-4cc9-9eb0-0d074c7f9093,
host id:

 delete the object
$ ibmcloud cos delete-object --bucket $COS_BUCKET --key '/cos-file.txt' --force

 delete the bucket
$ ibmcloud cos delete-bucket --bucket $COS_BUCKET --force

 delete the KP root key - this fails because the registration was not deleted
$ ibmcloud kp key delete $MY_COS_KEY_ID --output json

FAILED
kp.Error:
correlation_id='fffdd8a9-405a-4a91-a5a7-52c30d11424d',
msg='Conflict: Key could not be deleted. Please see "reasons" for more details.',
For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 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). 
 instance_ID Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 
 original_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.<br><br>Note: If you create a key without an x-kms-key-ring header, the key ring for the key is: default. 
 correlation_ID The unique identifier that is used to track and correlate transactions. 
 new_key_ring_ID Required. The unique identifier for the target key ring that you want to move the key to. 



A successful PATCH api/v2/keys/key_ID request returns the key's metadata, including the ID of the key ring that the key now belongs to.

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
Getting the details of a linked zone using the CLI 

To get the details of a linked zone using the API, run the following command:

ibmcloud dns cross-account linked-zone LINKED_ZONE_ID [-i, --instance INSTANCE] [--output FORMAT]

Where:



* LINKED_ZONE_ID is the ID of linked zone.
* -i, --instance value is the instance name or ID. If not set, the context instance specified by ibmcloud dns instance-target INSTANCE is used.
* --output value specifies the output format. Currently, json is the only supported format.







 Listing all linked zones using the API 

To list all linked zones using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* linked_dnszone_id which is the unique identifier of a linked zone.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3. When all variables are initiated, list the linked zones:

{
"description": "linked zone example",
"label": "dev"
}







 Getting the details of a linked zone using the API 

To get the details of a linked zone using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* linked_dnszone_id which is the unique identifier of a linked zone.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3. When all variables are initiated, get the details of the linked zone:
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/wrap



1. [Retrieve your service and authentication credentials to work with keys in the service.](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api)
2. Copy the key material of the DEK that you want to manage and protect.

If you have manager or writer privileges for your Hyper Protect Crypto Services service instance, [you can retrieve the key material for a specific key by making a GET /v2/keys/<key_ID> request](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-view-keysview-key-api).
3. Copy the ID of the root key that you want to use for wrapping.
4. Run the following cURL command to protect the key with a wrap operation.

curl -X POST 'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/wrap' -H 'accept: application/vnd.ibm.kms.key_action+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key_action+json' -H 'x-kms-key-ring: <key_ring_ID>' -H 'correlation-id: <correlation_ID>' -d '{
"plaintext": "<data_key>"
}'

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



Table 1. Describes the variables needed to wrap a specified key

 Variable Description 

 region Required. The region abbreviation, such as us-south or au-syd, that represents the geographic area where your Hyper Protect Crypto Services service instance resides.
To update the key ring of a key, you must have at least Manager service access to the key and the target key ring. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-accessservice-access-roles).
2. Update the key ring of a key by running the following curl command.

$ curl -X PATCH "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>" -H 'accept: application/vnd.ibm.kms.key+json' -H 'authorization: Bearer <IAM_token>' -H 'bluemix-instance: <instance_ID>' -H 'content-type: application/vnd.ibm.kms.key+json' -H "x-kms-key-ring: <original_key_ring_ID>" -H "correlation-id: <correlation_ID>" -d '{
"keyRingID": "<new_key_ring_ID>"
}'

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



Table 2. Describes the variables needed to update a key's key ring with the key management service API

 Variable Description 

 region Required. The region abbreviation, such as us-south, 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-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request.
If you know which key ring you want a key to be placed in, and you are a Manager of that key ring, you can also navigate to the Key rings panel, select ⋯ and click Add key to key ring. This will open the same panel you see by clicking Add on the Keys page with the Key rings variable filled in with the name of the key ring.





 Creating standard keys with the API 

Create a standard key by making a POST call to the following endpoint.

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



1. [Retrieve your service and authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).
2. Call the [Key Protect API](https://cloud.ibm.com/apidocs/key-protect) with the following curl command.

$ curl -X POST "https://<region>.kms.cloud.ibm.com/api/v2/keys" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "x-kms-key-ring: <key_ring_ID" -H "correlation-id: <correlation_ID>" -H "prefer: <return_preference>" -d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"name": "<key_name>",
"aliases": alias_list],
"description": "<key_description>",
"expirationDate": "<expiration_date>",
"extractable": <key_type>
}
]
}'
To update a custom resolver location using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* resolver_id, which is the unique identifier of a custom resolver.
* location_id, which is the custom resolver location ID.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3. When all variables are initiated, get the details of your custom resolver:

{
"enabled": false,
"subnet_crn": "crn:v1:bluemix:public:is:us-south-1:a/01652b251c3ae2787110a995d8db0135::subnet:0716-b49ef064-0f89-4fb1-8212-135b12568f04"
}
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/aliases/<alias>



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).
2. Delete a key alias by running the following curl command.

$ curl -X DELETE "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/aliases/<key_alias>" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "correlation-id: <correlation_ID>"

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



Table 2. Describes the variables needed to delete a key alias with the Hyper Protect Crypto Services API

 Variable Description 

 region Required. The region abbreviation, such as us-south, 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-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 key_ID Required. The unique identifier for the key. 
 key_alias Required. The unique, human-readable name that identifies your key. 
 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). 
 instance_ID Required.
* -f, --force allows for creating custom resolver with fewer than 2 locations.







 Create a custom resolver using the API 

To add a custom resolver using the API, follow these steps:



1. Set up your API environment with the correct variables.
2. Store the following values in variables to be used in the API command:



* instance_id, which is the unique identifier of a service instance.
* X-Correlation-ID, which is a string that uniquely identifies a request.



3. When all variables are initiated, add your custom resolver:



{
"name": "my-resolver",
"description": "custom resolver",
"locations": [
{
"subnet_crn": "crn:v1:bluemix:public:is:us-south-1:a/01652b251c3ae2787110a995d8db0135::subnet:0716-b49ef064-0f89-4fb1-8212-135b12568f04",
"enabled": false
}
]
}





 Next steps 



* [Adding custom resolver locations](https://cloud.ibm.com/docs/dns-svcs?topic=dns-svcs-cr-res-loc-add)
* [Setting up custom resolver forwarding rules](https://cloud.ibm.com/docs/dns-svcs?topic=dns-svcs-cr-fwd-rules-add)
* [Deleting a custom resolver](https://cloud.ibm.com/docs/dns-svcs?topic=dns-svcs-cr-delete)
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies



1. [Retrieve your service and authentication credentials](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api).
2. Create a rotation policy for a specified key by running the following cURL command.

curl -X PUT 
https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies 
-H 'authorization: Bearer <IAM_token>' 
-H 'bluemix-instance: <instance_ID>' 
-H 'correlation-id: <correlation_ID>' 
-H 'content-type: application/vnd.ibm.kms.policy+json' 
-d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.policy+json",
"rotation": {
"interval_month": <rotation_interval>
}
}
]
}'

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



Table 2. Describes the variables needed to create a rotation policy with the API

 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 service instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 port Required. The port number of the API endpoint. 
 key_ID Required.
For more information about key state, see [Monitoring the lifecycle of encryption keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-key-states). 
 Description (Optional) Add an extended description for your key. It needs to be 2 to 240 characters in length. 



6. When you finish filling out the key's details, click Create key to confirm.







 Creating standard keys with the API 

Create a standard key by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys



1. [Retrieve your service and authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api).
2. Call the [Hyper Protect Crypto Services key management service API](https://cloud.ibm.com/apidocs/hs-crypto) with the following cURL command.

curl -X POST "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "content-type: application/vnd.ibm.kms.key+json" -H "x-kms-key-ring: <key_ring_ID>" -H "correlation-id: <correlation_ID>" -H "prefer: <return_preference>" -d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key+json",
"collectionTotal": 1
},
"resources": [
{
"type": "application/vnd.ibm.kms.key+json",
"name": "<key_name>",
"aliases": alias_list],
"creationDate": "2021-07-08T17:02:10Z"
},
{
"id": "390086ac-76fa-4094-8cf3-c0829bd69526",
"creationDate": "2021-08-08T17:02:40Z"
},...10x]
]
}

Show more





 Example 5 

An optional flag to return the number of versions of a key that is not currently active. Previously, the command would have failed, as in the following example:

 Attempt to show version count
$ ibmcloud kp key versions af61298c-d75d-42a8-aa76-e04178cf4685 -i 99980ccc-d482-4cd0-bb41-deb4f7f1eb92 -t

Retrieving key Versions...
FAILED
KEY_ACTION_INVALID_STATE_ERR
Key is not in a valid state
Correlation-ID:a494bf49-be82-426f-88d8-17b58cc8634d

With CLI version 0.8.0 and higher, the command succeeds when adding the -a flag, as in the following example:

 Attempt to show version count
$ ibmcloud kp key versions af61298c-d75d-42a8-aa76-e04178cf4685 -i 99980ccc-d482-4cd0-bb41-deb4f7f1eb92 -t -a

Retrieving key Versions...
OK
TotalCount: 2
Key Version ID Creation Date
14dfde20-a751-4c3e-b6b0-e8d00a17d8d1 2023-06-22T15:16:09Z
af61298c-d75d-42a8-aa76-e04178cf4685 2023-06-22T15:10:28Z
https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>/metadata



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 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys), or by accessing the Key Protect dashboard.
3. 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](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-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.