---
name: ContinuousDelivery-key_protect_integration
title: Configuring Key Protect
description: IBM® Key Protect for IBM Cloud® helps you to securely store and apply secrets for apps across IBM Cloud services.
last-updated: 2026-07-23
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/ContinuousDelivery?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.

# Configuring Key Protect
{: #keyprotect}

DevOps Insights will reach end of service and be discontinued on **August 31, 2026**. Continuous Delivery will be discontinued in the following regions on 12 February 2027: **au-syd**, **ca-mon**, **ca-tor**, **us-east**. Code Risk Analyzer will also be discontinued in all regions on that date. If a region has no active usage of these features, the features in that region may be discontinued earlier and stop accepting new instances. [Learn more](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-faq_region_feature_consolidation&format=markdown)
{: important}

IBM® Key Protect for IBM Cloud® helps you to securely store and apply secrets for apps across IBM Cloud services.
{: shortdesc}

A *secret* is anything that provides access to sensitive information, such as an [API key](https://cloud.ibm.com/docs/iam?topic=iam-manapikey&format=markdown). If you store secrets as standard keys in Key Protect, you can use this tool integration to access secrets wherever they are needed in the toolchain workflow. To learn more about standard keys in Key Protect, see [Key types](https://cloud.ibm.com/docs/key-protect?topic=key-protect-envelope-encryption&format=markdown#key-types).

Before you configure a Key Protect tool integration, make sure that you have an instance of the Key Protect service provisioned in the region and resource group that you want to create the tool integration in. In certain scenarios, a Key Protect service instance can be automatically generated. For example, if you are minting a new API key and choose to store it as a secret for later use, you automatically generate the Key Protect service instance. For instructions to provision an instance of the Key Protect service, see [Provisioning the service](https://cloud.ibm.com/docs/key-protect?topic=key-protect-provision&format=markdown).
{: important}

Configure Key Protect to securely manage secrets that are part of your toolchain:

1. If you are configuring this tool integration as you are creating the toolchain, in the Configurable Integrations section, click **Key Protect**. If Key Protect is defined as an optional tool integration, it is located under **More Tools**. To create an authorization between the toolchain and the **Key Protect** service instance select the **Create an authorization for this toolchain** option from the **Authorization type** dropdown. This grants the toolchain access to the secret material stored in the **Key Protect** service instance.
1. If you have a toolchain and are adding this tool integration to it, from the IBM Cloud console, click the **Menu** icon ![hamburger icon](images/icon_hamburger.svg) > **Platform Automation** > **Toolchains**. On the Toolchains page, click the toolchain to open its Overview page. Alternatively, on your app's Overview page, on the Continuous Delivery card, click **View toolchain**. Then, click **Overview**.  

   a. Click **Add tool**.

   b. In the Tool Integrations section, click **Key Protect**.

1. Specify a name for this instance of the Key Protect tool integration to use in your toolchain. The name that you specify is used in the UI tools that select **Key Protect** secrets. It is also used as part of the reference that resolves the secret values when the toolchain runs. This instance name is also displayed on the Key Protect tool integration tile within the toolchain workspace.
1. Review the default values for **Region** and **Resource-Group** and update, if required.
1. Select the instance of the **Key Protect** service that you want to use.
1. To create an authorization between the toolchain and the **Key Protect** service instance click the **Create Authorization** button. This grants the toolchain access to the secret material stored in the **Key Protect** service instance.
1. Click **Create Integration**.
1. On the Toolchain's Overview page, on the **Third-Party tools** card, click **Key Protect**.

## Applying secrets
{: #apply_secrets}

After your Key Protect tool integration is configured, you can use it to apply secrets anywhere that they are needed by the toolchain. The following example applies a secret that is stored in Key Protect to an IBM Cloud API key that is required by the [Pipeline tool integration](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-deliverypipeline&format=markdown). You can follow the same steps to apply secrets to any of the Continuous Delivery tool integrations that require secret values.

You must save third-party secrets, such as a Slack webhook or an Artifactory API token, in Key Protect *before* you create a new toolchain. You can mint and store only IBM-managed secrets such as IBM Cloud API keys in Key Protect while you work with your toolchain.
{: important}

1. Click the key icon to retrieve secrets from secure stores such as Key Protect for the IBM Cloud API key.

1. In the **Provider** field, specify the provider and the name of the Key Protect tool integration that you use to manage your toolchain secrets. For example, to use the Key Protect tool integration, select `Key Project: ibm-keyprotect-secrets-1`. You can use other providers to manage your toolchain secrets, such as [HashiCorp Vault](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-hashicorpvault&format=markdown).

1. Select a secret name and click **OK** to apply the stored secret to the field that is associated with it.

![Secret Reference to a Vault](images/secret-pill.png){: caption="Secret reference to a vault" caption-side="bottom"}

The name of the secret that you select appears in capsule form. You cannot edit the secret name inline, but you can click ![remove icon](images/secret-pill-delete-16.png) to delete the name. You can also replace the secret name by using the Secrets Picker control again. If you manually type or paste a secret name into the Secrets field, it is displayed in a different format:

![Literal Secret Value](images/secret-literal.png){: caption="Secret value" caption-side="bottom"}

The format that the secret is displayed in indicates whether the value references a secret that is stored in a backend vault or is a secret that is stored in your toolchain. By using references to secrets that are managed by secret providers such as  Key Protect, your secret values are centralized and stored securely in a single location. This approach resolves secrets sprawl and proliferation, and means that you can update secrets without updating your toolchain. When you use secret references, the actual secret value is resolved when the toolchain runs by dynamically retrieving it from Key Protect. This approach is useful when you must rotate the value of your toolchain secrets periodically.

## Adding a Key Protect tool integration to your toolchain template
{: #add_toolchain_template}

You can add a Key Protect tool integration to your toolchain template by adding a service definition to the toolchain.yml file in your template repo. This file is the design blueprint for your toolchain and includes all of the tool integrations that are available when you create a toolchain instance based on that template. To customize an existing toolchain template to include a Key Protect tool integration, insert a YAML definition. 

```yaml
  kp-tool:
    service_id: keyprotect
    parameters:
      name: kp-compliance-secrets
      region: us-south
      resource-group: default
      instance-name: ffs-secrets
      setup-authorization-type: create
```

In certain scenarios, you can add a Key Protect tool integration dynamically while creating a toolchain. For example, if you click **New** to mint a new API key, you can select the **Save this key in a secrets store for reuse** checkbox to save the API key in a Key Protect instance to use it again later. If you do not already have a Key Protect instance, a new instance is created for you.
{: tip}

## Authorizing your toolchain to access secrets
{: #key_protect_authorize_secrets}

References to secrets that are stored in Key Protect are dynamically resolved when the toolchain runs. To access the required secrets, you must authorize your toolchain to access the Key Protect instance. If you are creating a toolchain from a template use the **Authorization type** dropdown when configuring the **Key Protect** integration. If you are adding a **Key Protect** integration to an existing toolchain use the **Create authorization** button.

To view your authorizations in IBM Cloud, complete the following steps:

1. From the IBM Cloud console, click **Manage** > **Access (IAM)**.
1. Click **Authorizations**.

You can also access your authorizations on the [Manage authorizations](https://cloud.ibm.com/iam/authorizations){: external} page. 
{: tip}

![Toolchain Authorizations for Key Protect](images/s2s-auths.png){: caption="Toolchain authorizations for Key Protect" caption-side="bottom"}

You can create the authorization manually, if required. To successfully resolve the secret references, your toolchain instance must have both `Viewer` and `ReaderPlus` access to the correct Key Protect service instance.

## Configuring Key Protect by using the API
{: #keyprotect-config-parameters}

The Key Protect tool integration supports the following configuration parameters that you can use with the [Toolchain HTTP API and SDKs](https://cloud.ibm.com/apis/toolchain){: external} when you [create](https://cloud.ibm.com/apis/toolchain#create-tool){: external}, [read](https://cloud.ibm.com/apis/toolchain#get-tool-by-id){: external}, and [update](https://cloud.ibm.com/apis/toolchain#update-tool){: external} tool integrations.

You must specify the `tool_type_id` property in the request body with the `keyprotect` value.
{: important}

| Parameter | Usage | Type | Terraform argument | Description |
| --- | --- | --- | --- | --- |
| instance-name | required, updatable | String | instance_name | The name of the Key Protect service instance. |
| name | required, updatable | String | name | The name of this tool integration. Secret references include this name to identify the secrets store where the secrets reside. All of the secrets store tools that are integrated into a toolchain must have a unique name to allow secret resolution to function properly. |
| region | required, updatable | String | location | The IBM Cloud region where the Key Protect service instance is located. |
| resource-group | required, updatable | String | resource_group_name | The name of the resource group where the Key Protect service instance is located. |
{: caption="Key Protect tool integration parameters" caption-side="bottom"}

## Learn more about Key Protect
{: #keyprotect_learn_more}

To learn more about Key Protect, see [Service overview](https://cloud.ibm.com/docs/key-protect?topic=key-protect-about&format=markdown).