---
name: schematics-integration-kms
title: KMS integration for BYOK or KYOK
description: IBM Cloud® Schematics integrates to fully manage enterprise-grade key management to manage the lifecycle of your encryption keys that are used in your Cloud resources, services, and applications.
last-updated: 2026-04-29
---

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

# KMS integration for BYOK or KYOK
{: #kms-integration}

IBM Cloud® Schematics integrates to fully manage enterprise-grade key management to manage the lifecycle of your encryption keys that are used in your Cloud resources, services, and applications.
{: shortdesc}

## Launching key management
{: #key-mgt-ui}

By default the data that you store in Schematics workspaces using the Enterprise plan is encrypted by using randomly generated keys. If you need to control the encryption keys, you can use the IBM Key Protect to create, import, and manage encryption root keys and standard keys. Then, you can associate those keys with your Schematics resource deployment to encrypt your resources.
{: shortdesc}

You can use your encryption keys from IBM Key Protect (available as Multi-Tenant for BYOK or Dedicated for KYOK) to encrypt and secure data stored in Schematics. For more information about how to protect sensitive data in Schematics, see [protecting your sensitive data in Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-secure-data&format=markdown#data-storage).

Hyper Protect Crypto Services (HPCS) has been deprecated. If you are currently using HPCS, migrate to Key Protect Dedicated for KYOK capabilities.
{: deprecated}

### Before you begin
{: #kms-key-prerequisites}

The key management system lists the instance that are created from your specific location and region. Following prerequisites are followed to perform the KMS activity.


- You should have your BYOK or KYOK. To create IBM Key Protect keys, see [create Key Protect instance](https://cloud.ibm.com/catalog/services/key-protect). Choose Multi-Tenant for BYOK or Dedicated for KYOK deployment.
- You need to [add root key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-import-root-keys&interface=ui&format=markdown#import-root-key-gui) to your Key Protect instance.
- You need to configure [service to service authorization](https://cloud.ibm.com/docs/iam?topic=iam-serviceauth&interface=ui&format=markdown#create-auth) to integrate Key Protect in Schematics service. Follow these steps to grant service to service authorization Key Protect access to Schematics service.


    1. In the IBM Cloud console, click **Manage** > **Access (IAM)**, and select **Authorizations** > **Create**.
    2. Select a **Source Service** as **Schematics**.
    3. Select **Target Service** as **Key Protect**. Select the instance you want to provide authorization.
    4. Select the **Role** as **Reader**.
    5. Click **Authorize**.

For more information, see IAM authorization to create by using [CLI](https://cloud.ibm.com/docs/iam?topic=iam-serviceauth&interface=cli&format=markdown#auth-cli), and [API](https://cloud.ibm.com/docs/iam?topic=iam-serviceauth&interface=ui&format=markdown#create-auth).
{: note}

KMS setting is a one time settings. You need to open the [support ticket](https://cloud.ibm.com/docs/support?topic=support-using-avatar&format=markdown) to update KMS settings.
{: note}

### Enabling IBM Key Protect through UI
{: #integrate-byok-ui}
{: ui}

Follow these steps to launch key management system and encrypt your keys with Schematics.

1. Log in to [IBM Cloud console](https://cloud.ibm.com/){: external}.
2. Click the **Menu** icon ![hamburger icon](images/icon_hamburger.svg) > **Platform Automation** > **Schematics** > [**Extensions**](https://cloud.ibm.com/automation/schematics/extensions/agents){: external}.
3. Click **Connect** > **Key Management** from the drop down.
4. Select **Service** as **Key Protect**, or **Hyper Protect Crypto Services**.
5. Select an **Choose existing instance** instance. If your instance not created, select an **Create a new instance** to create IBM Key Protect, or IBM Cloud Hyper Protect Crypto Services. For more information, see [Create a key protect instance](#kms-key-prerequisites).

    You can view your instance in the service list, when the prerequisites are met. Or you can see a message **No Keys** found.
    {: note}

6. Select your **Service** and **Root key** that is configured for BYOK or KYOK.
7. Click **Update** to complete the integration of your keys with your Schematics resource deployment.
8. Click **Launch** icon to view your enabled keys in the **Resource list**.

### Enabling IBM Key Protect through CLI
{: #integrate-byok-cli}
{: cli}

Follow the steps to integrate root keys with Schematics to encrypt the data through command-line.

1. [Download and install command-line](https://cloud.ibm.com/docs/cli?topic=cli-install-ibmcloud-cli&format=markdown).
2. List all the KMS instance in your IBM Cloud account to find your Key Protect or Hyper Protect Crypto Services instances.

    ```sh
    ibmcloud schematics kms instances ls --location LOCATION_NAME --scheme ENCRYPTION_SCHEME
    ```
    {: pre}

3. Integrate the root key with Schematics to encrypt your data in the specified location.

    ```sh
    ibmcloud schematics kms enable --location LOCATION_NAME --scheme ENCRYPTION_SCHEME --group RESOURCE_GROUP --primary_name PRIMARY_KMS_NAME --primary_crn PRIMARY_KEY_CRN --primary_endpoint PRIMARY_KMSPRIVATEENDPOINT --secondary_name SECONDARY_KMS_NAME --secondary_crn SECONDARY_KEY_CRN --secondary_endpoint SECONDARY_KMSPRIVATEENDPOINT
    ```
    {: pre}

4. Get current root key information.

    ``` sh
    ibmcloud schematics kms info --location LOCATION_NAME
    ```
    {: pre}

    For more information about enabling the `BYOK` or `KYOK` commands, see [Enable BYOK or KYOK commands](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#kms-commands).
    {: note}