--- name: hs-crypto-set-dual-auth-policy title: Setting dual authorization policies for keys description: authorization policies for individual root keys or standard keys. last-updated: 2026-07-01 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/hs-crypto?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Setting dual authorization policies for keys {: #set-dual-auth-key-policy} IBM Cloud® Hyper Protect Crypto Services is deprecated. As of 28 March 2026, you can't create new instances, and access to free instances will be removed. Existing premium plan instances are supported until 28 March 2027. Any instances that still exist on that date will be deleted. {: deprecated} You can use IBM Cloud® Hyper Protect Crypto Services to set dual authorization policies for individual root keys or standard keys. {: shortdesc} Dual authorization is an extra policy that helps to prevent accidental or malicious deletion of encryption keys in your Hyper Protect Crypto Services instance. When you enable this policy at the key level, Hyper Protect Crypto Services requires an authorization from two users to delete an encryption key. After you enable dual authorization at the key level, the policy that is associated with the key can no longer be changed to allow a single authorization to delete the encryption key. {: important} To enable dual authorization settings at the instance level, check out [Managing service settings](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-dual-auth&format=markdown). {: tip} ## Managing dual authorization policies with the key management service API {: #manage-dual-auth-key-policies-api} Consider the following items before you enable dual authorization for a key: - **Determine whether a dual authorization policy is required for the key.** As a security admin, assess the sensitivity of your workload to determine whether a key requires a dual authorization policy based on your requirements. After you enable dual authorization for a key, the policy can no longer be changed to allow a single authorization to delete the key. - **Determine who can authorize deletion of your Hyper Protect Crypto Services resources.** After you create a dual authorization policy for a key, the key will require [an action from two users](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-dual-auth-keys&format=markdown) before it can be deleted. Be sure to identify two distinct users with the [appropriate levels of access](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access&format=markdown#service-access-roles) to the instance or key. To learn how to delete a key that has a dual authorization policy, see [Deleting keys using dual authorization](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-dual-auth-keys&format=markdown). ### Viewing a dual authorization policy for a key {: #view-dual-auth-key-policy-api} For a high-level view, you can retrieve the dual authorization policy for a single key by making a `GET` call to the following endpoint. ``` https://.api..hs-crypto.appdomain.cloud/api/v2/keys//policies?policy=dualAuthDelete ``` {: codeblock} 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&format=markdown). To work with dual authorization policies, you must be assigned a _Manager_ access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access&format=markdown#service-access-roles). {: note} 2. Retrieve the dual authorization policy for a specified key by running the following cURL command. ```cURL curl -X GET \ 'https://.api..hs-crypto.appdomain.cloud/api/v2/keys//policies?policy=dualAuthDelete' \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' \ -H 'accept: application/vnd.ibm.kms.policy+json' ``` {: codeblock} Replace the variables in the example request according to the following table. | Variable | Description | | --- | --- | | `key_ID` | **Required.** The unique identifier for the key that has an existing rotation policy. | | `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-regions&format=markdown#service-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/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown). | | `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&format=markdown). | {: caption="Describes the variables needed to view a dual authorization policy for a key with the API" caption-side="bottom"} A successful request returns dual authorization policy details that are associated with your key. The following JSON object shows an example response for a key that has an existing dual authorization policy. ```json { "metadata": { "collectionTotal": 1, "collectionType": "application/vnd.ibm.kms.policy+json" }, "resources": [ { "id": "02fd6835-6001-4482-a892-13bd2085f75d", "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d", "dualAuthDelete": { "enabled": true }, "createdBy": "...", "creationDate": "2020-03-10T20:41:27Z", "updatedBy": "...", "lastUpdateDate": "2020-03-16T20:41:27Z" } ] } ``` {: screen} For keys that do not have an existing dual authorization policy, the following JSON shows an example response. ```json { "metadata": { "collectionTotal": 0, "collectionType": "application/vnd.ibm.kms.policy+json" } } ``` {: screen} ### Creating a dual authorization policy for a key {: #create-dual-auth-key-policy-api} Create a dual authorization policy for single key by making a `PUT` call to the following endpoint. ``` https://.api..hs-crypto.appdomain.cloud/api/v2/keys//policies?policy=dualAuthDelete ``` {: codeblock} After you enable a dual authorization policy for a single key, the policy cannot be reverted. {: important} 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&format=markdown). To work with dual authorization policies, you must be assigned a _Manager_ access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out [Service access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access&format=markdown#service-access-roles). {: note} 2. Enable dual authorization for a specified key by running the following cURL command. ```cURL curl -X PUT \ 'https://.api..hs-crypto.appdomain.cloud/api/v2/keys//policies?policy=dualAuthDelete' \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' \ -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", "dualAuthDelete": { "enabled": true } } ] }' ``` {: codeblock} Replace the variables in the example request according to the following table. | Variable | Description | | --- | --- | | `key_ID` | **Required.** The unique identifier for the key that you want to create a dual authorization policy for. | | `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-regions&format=markdown#service-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/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown). | | `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&format=markdown). | {: caption="Describes the variables needed to update a dual authorization policy with the API" caption-side="bottom"} A successful request returns a `200 OK` response with dual authorization policy details for your key. The following JSON object shows an example response. ```json { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2", "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2", "dualAuthDelete": { "enabled": true }, "createdBy": "...", "creationDate": "2020-03-10T20:41:27Z", "updatedBy": "...", "lastUpdateDate": "2020-03-16T20:41:27Z" } ] } ``` {: screen} The key now requires an authorization from two users before it can be deleted. For more information, see [Deleting keys using dual authorization](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-delete-dual-auth-keys&format=markdown).