--- name: key-protect-provision title: Creating an instance description: You can create an instance of IBM® Key Protect for IBM Cloud® by using the IBM Cloud console or the IBM Cloud CLI. last-updated: 2026-05-26 --- {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:external: target="_blank" .external} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:term: .term} # Creating an instance {: #provision} You can create an instance of IBM® Key Protect for IBM Cloud® by using the IBM Cloud console or the IBM Cloud CLI. {: shortdesc} ## Overview {: #provision-overview} In Key Protect, an `instance` (sometimes referred to as a `service instance`) is a namespace. A namespace organizes keys into logical groups and provides isolation and protection between namespaces. - For example, you may choose to have two Key Protect instances - one for the finance department and one for manufacturing. Two instances provides isolation so keys in one business unit are not accessible from other business units. The term `instance` is sometimes used to describe compute resources, such as [virtual servers](https://cloud.ibm.com/docs/virtual-servers?topic=virtual-servers-getting-started-tutorial){: external} or [virtual server instances for VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-about-advanced-virtual-servers){: external}. An instance, in Key Protect should **not** be equated with compute resources. A Key Protect instance is a namespace. ## Provisioning Key Protect Standard or Dedicated instance from the IBM Cloud console {: #provision-gui} To provision an instance of Key Protect from the IBM Cloud console, complete the following steps. 1. [Log in to your IBM Cloud account](https://cloud.ibm.com/login/){: external}. 2. Click **Catalog** to view the list of services that are available on IBM Cloud. 3. Search for "Key Protect" in the ***Search the catalog...*** field and click `Key Protect`. 4. Select a Standard or Dedicated plan, and click **Create** to provision an instance of Key Protect in the account, region, and resource group where you are logged in. For more information about pricing, check out [Pricing for Key Protect on IBM Cloud](https://cloud.ibm.com/docs/key-protect?topic=key-protect-pricing-plan). If you need to repeat the same setup across accounts or environments, you can automate it with curated [Terraform IBM Modules](https://registry.terraform.io/namespaces/terraform-ibm-modules){: external}. The [Key Protect All-Inclusive module](https://registry.terraform.io/modules/terraform-ibm-modules/kms-all-inclusive/ibm/latest){: external} is one option that can provision an instance together with keys and key rings. For an overview, see [Terraform IBM Modules](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-about-tim). {: tip} ## Provisioning Key Protect from the IBM Cloud CLI {: #provision-cli} You can also provision an instance of Key Protect by using the IBM Cloud CLI. While the following examples use the `tiered-pricing` plan, you can also deploy resources into select regions using the [`cross-region-resiliency` plan](https://cloud.ibm.com/docs/key-protect?topic=key-protect-pricing-plan), which offers additional failover support. The regions where this plan is available are `us-south` (located in Dallas, United States), `jp-tok` (located in Tokyo, Japan), and `eu-de` (located in Frankfurt, Germany). You cannot to use this plan to deploy into other regions. {: important} ### Login using the CLI {: #provision-login-cli} Login to IBM Cloud through the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started){: external}. This is the account used for this instance of Key Protect. ## Login {: #provision-login} Login with the `login` command. If this fails you should try the `--sso` option to login with a federated ID (see the next section). This example fails because the email address belongs to a federated ID. ```sh ibmcloud login ``` {: pre} ### Example {: #provision-login-example} ```sh $ ibmcloud login API endpoint: https://cloud.ibm.com Region: us-south Email> Password> Authenticating... You are using a federated user ID, please use one time passcode ( ibmcloud login --sso ), or use API key ( ibmcloud --apikey key or @key_file ) to authenticate. API endpoint: https://cloud.ibm.com Region: us-south Not logged in. FAILED ``` {: screen} ## Login with a federated ID {: #provision-login-federated} Logging in with the `--sso` option opens a browser window (requires a login) and creates a one-time passcode. The passcode is used to complete the login process. ```sh ibmcloud login --sso ``` {: pre} ### Example {: #provision-login-federated-example} ```sh $ ibmcloud login --sso API endpoint: https://cloud.ibm.com Region: us-south Get One Time Code from https://identity-2.us-south.iam.cloud.ibm.com/identity/passcode to proceed. Open the URL in the default browser? [Y/n] > Y One Time Code > Authenticating... OK Select an account: 1. Account name (ea988d3289c24739a0977651b46fb145) Enter a number> 1 Targeted account Account name (ea988d3289c24739a0977651b46fb145) API endpoint: https://cloud.ibm.com Region: us-south User: Account: Account name (ea988d3289c24739a0977651b46fb145) Resource group: No resource group targeted, use 'ibmcloud target -g RESOURCE_GROUP' CF API endpoint: Org: Space: ``` {: screen} ## Select a region and resource group {: #provision-select-region} Select the region and resource group where you would like to create a Key Protect instance. The `` can be `Default` (case-sensitive). ```sh ibmcloud target -r -g ``` {: pre} ### Example {: #provision-select-region-example} ```sh $ ibmcloud target -r us-south -g Default Targeted resource group Default Switched to region us-south API endpoint: https://cloud.ibm.com Region: us-south User: Account: Account name (ea988d3289c24739a0977651b46fb145) Resource group: Default CF API endpoint: Org: Space: ``` {: screen} ## Provision a public instance {: #provision-public} Provision a public Key Protect instance. The next section has an example of provisioning a `private` instance. - Public endpoints are **outside** the IBM Cloud. - Private endpoints are **inside** the IBM Cloud. A public instance accepts API requests from both `public and private` endpoints. Public network access is the default setting and is used if a policy is not set. A private instance accepts API requests from only `private` endpoints. See [Managing network access policies](https://cloud.ibm.com/docs/key-protect?topic=key-protect-access-control-with-cbr) for learn more about public and private access. **Note** the GUID is the instance ID. In this example, the instance ID is `ea557753-a15b-4570-a9a3-1efefbd2d382`. ```sh ibmcloud resource service-instance-create kms tiered-pricing ``` {: pre} ### Example {: #provision-public-example} ```sh # create a public service instance $ ibmcloud resource service-instance-create kms tiered-pricing us-south Creating service instance in resource group Default of account as ... OK Service instance was created. Name: ID: crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:ea557753-a15b-4570-a9a3-1efefbd2d382:: GUID: ea557753-a15b-4570-a9a3-1efefbd2d382 Location: us-south State: active Type: service_instance Sub Type: kms Allow Cleanup: false Locked: false Created at: 2020-05-31T15:04:50Z Updated at: 2020-05-31T15:04:50Z Last Operation: Status create succeeded Message Completed create instance operation # list the service instances $ ibmcloud resource service-instances Retrieving instances with type service_instance in resource group Default in all locations under account as ... OK Name Location State Type us-south active service_instance # delete the public service instance $ ibmcloud resource service-instance-delete Deleting service instance in resource group Default under account as ... Really delete the service instance with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:ea557753-a15b-4570-a9a3-1efefbd2d382::? [y/N] > y OK Service instance with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:ea557753-a15b-4570-a9a3-1efefbd2d382:: is deleted successfully ``` {: screen} ## Provision a private instance {: #provision-private} Provision a private Key Protect instance. Remember that a private instance accepts API requests from only private endpoints, which are inside the IBM Cloud. You cannot use the CLI with a private instance if you are outside the IBM Cloud. ```sh ibmcloud resource service-instance-create kms tiered-pricing -p '{"allowed_network": "private-only"}' ``` {: pre} ### Example {: #provision-private-example} After the private instance is created, a request is made to create a key. The request fails because the user does not have access to the `private` instance from outside the IBM Cloud. The `-p` option specifies a JSON file or JSON string of parameters used to create the service instance. ```sh # create a private service instance $ ibmcloud resource service-instance-create kms tiered-pricing us-south -p '{"allowed_network": "private-only"}' Creating service instance in resource group Default of account as ... OK Service instance was created. Name: ID: crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6:: GUID: a152eee4-262e-4a39-ae13-a71b9882dcb6 Location: us-south State: active Type: service_instance Sub Type: kms Allow Cleanup: false Locked: false Created at: 2020-05-31T15:10:23Z Updated at: 2020-05-31T15:10:23Z Last Operation: Status create succeeded Message Completed create instance operation # list the service instances $ ibmcloud resource service-instances Retrieving instances with type service_instance in resource group Default in all locations under account as ... OK Name Location State Type us-south active service_instance # list the private service instance $ ibmcloud resource service-instance Retrieving service instance in resource group Default under account as ... OK Name: ID: crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6:: GUID: a152eee4-262e-4a39-ae13-a71b9882dcb6 Location: us-south Service Name: kms Service Plan Name: tiered-pricing Resource Group Name: Default State: active Type: service_instance Sub Type: kms Created at: 2020-05-31T15:10:23Z Created by: Updated at: 2020-05-31T15:10:23Z Last Operation: Status create succeeded Message Completed create instance operation # list keys in the private service instance $ ibmcloud kp keys -i a152eee4-262e-4a39-ae13-a71b9882dcb6 Retrieving keys... FAILED kp.Error: correlation_id='59578794-2b5b-48ca-9074-bbe23760d94a', msg='Unauthorized: The user does not have access to the specified resource' # delete the private service instance $ ibmcloud resource service-instance-delete Deleting service instance in resource group Default under account as ... Really delete the service instance with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6::? [y/N] > y OK Service instance with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6:: is deleted successfully ``` {: screen} ## Deleting an instance with existing keys {: #provision-delete} You cannot delete a service instance that contains keys. ### Example {: #provision-delete-example} ```sh $ ibmcloud resource service-instance-delete Deleting service instance in resource group Default under account as ... Really delete the service instance with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6::? [y/N] > y FAILED Error Code: RC-ServiceBrokerErrorResponse Message: [409, Conflict] Conflict: Instance contains 2 active keys. Remove all keys before de-provisioning ``` {: screen} ## What's next {: #provision-service-next-steps} To find out more about programmatically managing your keys, [check out the Key Protect API reference doc](https://cloud.ibm.com/apidocs/key-protect){: external}.