vania-janet/multiturn-rag-retrieval-data huggingface dataset:
$ curl -X POST "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/key_rings/<key_ring_id>" -H "authorization: Bearer <IAM_token>" -H "bluemix-instance: <instance_ID>" -H "correlation-id: <correlation_ID>"

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



Table 1. Describes the variables needed to create a 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. 
 key_ring_id Required. The unique identifier for the key ring that you would like to create. 
 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). 
 correlation_ID The unique identifier that is used to track and correlate transactions. 



A successful POST api/v2/key_rings request returns an HTTP 201 Created response, which indicates that the key ring is created and is now available for holding standard and root keys.









 Transferring a key to a different key ring
curl -X GET "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID_or_alias>" -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 4. Describes the variables needed to view a specified key 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 instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regionsservice-endpoints). 
 key_ID_or_alias Required. The identifier or alias for the key that you want to retrieve. 
 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 instance. For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID). 
 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.
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>" -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": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
"extractable": <key_type>
}
]
}'

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



Table 2. Describes the variables needed to add a root key with the API

 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. 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.
Retrieving a key 

You can retrieve the key material for a key by using IBM® Key Protect for IBM Cloud®.

If you have a Writer or Manager access policy, you can retrieve the contents of a standard key, such as its key material and policy details.

Root keysstay within the bounds of a hardware security module. The key material for a root key cannot be retrieved.



 Retrieving a key 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>



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. Retrieve the ID of the key that you would like to access or manage.

The ID value is used to access detailed information about the key, such as the key material itself. You can retrieve the ID for a specified key by making a GET /v2/keys request, or by accessing the Key Protect GUI.
3. Run the following curl command to get details about your key and the key material.

$ curl -X GET "https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>" -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 specified 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.
curl -X GET "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/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>'

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



Table 2. Describes the variables needed to view keys with the API

 Variable Description 

 region The region abbreviation, such as us-south or au-syd, 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. 
 IAM_token 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 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). 
 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: The key ring ID of keys that are created without an x-kms-key-ring header is: default.
If your private network gateway has both an IPv4 and an IPv6 address, it is recommended that you include the --ipv4 flag in all of your curl requests to ensure that the requests are resolved to IPv4.

ipWhitelist has been deprecated and replaced with allowedIP. If there isn't a query parameter specified in your GET instance policies request, you will see duplicate records when you retrieve your allowed IP policy.

The following example shows how to utilize the --ipv4 flag in a GET instance policies request via a private endpoint.

$ curl -k -L --ipv4 -X GET "https://private.<region>.kms.cloud.ibm.com:<private_enpoint_port>/api/v2/instance/policies" -H "accept: application/vnd.ibm.kms.policy+json" -H "authorization: Bearer <token>" -H "bluemix-instance: <instance_ID>" -H "correlation-id: <correlation_ID>"

When using the --ipv4 flag, the flag should come before the -X flag to avoid running into issues with the curl request.



 Retrieving the private port for an allowed IP policy enabled Key Protect instance 

You can retrieve the private endpoint port associated with your Key Protect instance's active allowed IP policy by making a GET call to the following endpoint. Note that calls to this API bypass allowed IP policy enforcement.

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



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

To retrieve the private endpoint port associated with your allowed IP policy, you must be assigned a Manager access policy for your Key Protect instance. To learn how IAM roles map to Key Protect service actions, check out [Service access roles](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-accessmanage-access-roles).
2.
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'

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



Table 1. 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. The unique identifier for the root key that has an existing rotation policy. 
 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). 
 correlation_ID The unique identifier that is used to track and correlate transactions. 



A successful GET api/v2/keys/{id}/policies response returns policy details that are associated with your key. The following JSON object shows an example response for a root key that has an existing rotation policy.

{
$ curl -X GET "https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_ID_or_alias>" -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 specified 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. <br> <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 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>For more information, see [Retrieving an instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID). 
 correlation_ID Optional. The unique identifier that is used to track and correlate transactions. 
 offset_limit Optional. By default, GET /key_rings returns a sequence of 51 keyRings including the default keyRing. To retrieve a different set of key rings, use limit with offset to paginate through your available resources. The maximum value for limit is '5,000.' 
 offset_value Optional. By specifying offset, you retrieve a subset of key rings that starts at the offset value. 
 show_total Optional. If set to true, the response metadata returns a value for totalCount in use with pagination. 



A successful GET api/v2/key_rings request returns a collection of key rings that are available in your Key Protect service instance.

{
"metadata": {
"collectionType": "application/vnd.ibm.kms.key_ring+json",
"collectionTotal": 2
},
"resources": [
{
"id": "default"
},
{
"id": "Sample Key Ring 2",
"creationDate": "2020-03-12T11:00:06Z",
"createdBy": "..."
}
]
}





 Deleting key rings with the API 

You can delete a key ring by making a DELETE call to the following endpoint.

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

This action won't succeed if the key ring contains at least one key, regardless of key state (including keys in the Destroyed state).



1.
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:

curl -X GET "https://api.dns-svcs.cloud.ibm.com/v1/instances/test/linked_dnszones/example" -H "accept: application/json" -H "X-Correlation-ID: property"
: Calculates the Z-score of a time series with the specified mean (second parameter) and standard deviation (third parameter).

TS_PEAK(DoubleTimeSeries)
: Output: DoubleTimeSeries
: Returns the peaks of the time series.

TS_TROUGH(DoubleTimeSeries)
: Output: DoubleTimeSeries
: Returns the troughs of the time series.

TS_DIFF(DoubleTimeSeries)
: Output: DoubleTimeSeries
: Returns the difference of the time series.

TS_CORRELATION(DoubleTimeSeries, DoubleTimeSeries)
: Output: Double
: Returns the correlation between two time series.

TS_SEG_CORRELATION(DoubleSegmentTimeSeries, DoubleSegmentTimeSeries)
: Output: DoubleTimeSeries
: Returns the correlation between each pair of corresponding segments in the two input time series. Each timetick in the output time series is the timetick of the corresponding segment.

TS_MANHATTAN_DISTANCE()
: Output: Double
: Returns the [Manhattan distance](https://en.wikipedia.org/wiki/Taxicab_geometry) between two time series.

TS_SEG_MANHATTAN_DISTANCE(DoubleSegmentTimeSeries, DoubleSegmentTimeSeries)
: Output: DoubleTimeSeries
: Returns the [Manhattan distance](https://en.wikipedia.org/wiki/Taxicab_geometry) between each pair of corresponding segments in the two input time series. Each timetick in the output time series is the timetick of the corresponding segment.

TS_SBD()
: Output: Double
: Returns the shape-based distance between two time series.

TS_SEG_SBD(DoubleSegmentTimeSeries, DoubleSegmentTimeSeries)
: Output: DoubleTimeSeries
: Returns the shape-based distance between each pair of corresponding segments in the two input time series. Each timetick in the output time series is the timetick of the corresponding segment.

TS_DTW()
: Output: Double
-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": <new_rotation_interval>
}
}
]
}'

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



Table 3. 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. The unique identifier for the root key that you want to replace a rotation policy for. 
 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).
$ 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": [
{
"type": "application/vnd.ibm.kms.key+json",
"name": "<key_name>",
"aliases": alias_list],
"description": "<key_description>",
"expirationDate": "<expiration_date>",
"payload": "<key_material>",
"extractable": <key_type>
}
]
}'

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





Table 1. Describes the variables that are needed to add a standard 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. <br> <br>For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regionsservice-endpoints). 
 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.
$ curl -X PUT "https://us-south.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess" -H "accept: application/vnd.ibm.kms.policy+json" -H "authorization: Bearer $ACCESS_TOKEN" -H "bluemix-instance: $KP_INSTANCE_ID" -H "content-type: application/vnd.ibm.kms.policy+json" -d '{
"metadata": {
"collectionType": "application/vnd.ibm.kms.policy+json",
"collectionTotal": 1
},
"resources": [
{
"policy_type": "keyCreateImportAccess",
"policy_data": {
"enabled": true,
"attributes": {
"create_root_key": true,
"create_standard_key": false,
"import_root_key": true,
"import_standard_key": true,
"enforce_token": true
}
}
}
]
}'

 step 2a - fails when using the ibmcloud CLI
 because the instance policy prevents creating standard keys
$ ibmcloud kp key create my-standard-key --standard-key

FAILED
kp.Error:
correlation_id='43c45c85-7a1f-478c-b235-49decec8c88f',
msg='Conflict:
Key could not be created:
Please see reasons for more details (KEY_CREATE_IMPORT_ACCESS_ERR)',
reasons='[KEY_CREATE_IMPORT_ACCESS_ERR:
KeyCreateImportAccess instance policy does not allow this action -
FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'

 step 2b - fails when using the the ibmcloud API
 because the instance policy prevents creating standard keys
"type": "application/vnd.ibm.kms.key+json",
"name": "<key_name>",
"aliases": alias_list],
"description": "<key_description>",
"expirationDate": "<expiration_date>",
"extractable": <key_type>
}
]
}'

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





Table 1. Describes the variables that are needed to add a standard key.

 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). 
 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 that you would like the newly create key to be a part of. If unspecified, the header is automatically set to 'default' and the key will sit in the default key ring in the specified Key Protect service instance. 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.
[Actions icon](https://cloud.ibm.com/docs-content/v1/content/217f108cc44e2ce15fb692d4b57b4c628464e908/icons/action-menu-icon.svg) to open a list of options for a specific key.
6. From the options menu, click Edit key rotation policy to manage the rotation policy for the key.
7. Switch the Key rotation to On and move the slider to select a frequency of rotation in months.

If your key has an existing rotation policy, the interface displays the key's existing rotation period.
8. Click Save policy to set the policy for the key.



When it's time to rotate the key based on the rotation interval that you specify, Hyper Protect Crypto Services automatically replaces the root key with new key material.





 Managing rotation policies with the API 



 Viewing a rotation policy 

For a high-level view, you can browse the rotation policies that are associated with a root key by making a GET call to the following endpoint.

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. Retrieve the rotation policy for a specified key by running the following cURL command.

curl -X GET 
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'

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



Table 1.