---
name: schematics-integration-secretsmanager
title: Integrating Secrets Manager in Schematics
description: IBM Cloud® Schematics supports integration with IBM Cloud® Secrets Manager that allows you to securely manage sensitive information without displaying actual secret values in Schematics configurations. Instead of hardcoding secrets, you can provide the secret reference directly from Secrets Manager to enhance security and simplify your secret rotation.
last-updated: 2026-05-27
---

> ## 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.

# Integrating Secrets Manager in Schematics
{: #sm-integration}

IBM Cloud® Schematics supports integration with [IBM Cloud® Secrets Manager](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-key-value&interface=ui&format=markdown) that allows you to securely manage sensitive information without displaying actual secret values in Schematics configurations. Instead of hardcoding secrets, you can provide the secret reference directly from Secrets Manager to enhance security and simplify your secret rotation.
{: shortdesc}

Integrating Secrets Manager in Schematics eliminates the need to expose secret values in automation stacks such as Terraform, Ansible, and Extensions. With direct secret rotation and improved security, Secrets Manager enhances the maintainability of your Schematics workflows.

To integrate Secrets Manager in Schematics and access the secrets. you need to create a service to service policy between Secrets Manager and Schematics and assign `Viewer` and `Secret Reader` roles.

## Before you begin
{: #sm-integration-prerequisites}

- You must have your key-value secrets. To create the secrets, see [create Secrets Manager instance](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&interface=ui&format=markdown).
- 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 Secrets Manager in Schematics service.
- Follow these steps to grant service to service authorization access to Schematics service.

1. Log in to [IBM Cloud console](https://cloud.ibm.com/){: external}.
2. Click **Manage** > **Access (IAM)** > **Authorizations** > **Create**.
3. Select a **Source account** as **This account**.
4. Select **Service** as **Schematics**.
5. Select **Resources** as **All resources** or **Specific resources**.
6. Select Target **Service** as Secrets Manager.
7. Select the **Role** as **Viewer** and **Secret Reader**.
8. Select **Authorize dependent services** to enable authorization to be delegated by source and dependent services.
9. Click **Authorize**.

## Integrating Secrets Manager in Schematics Terraform by using console
{: #sm-integrate-wks}
{: ui}

Follow the steps to enable Secrets Manager in Schematics to securely connect with Schematics Terraform.

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** > **Terraform** > [**Create workspace**](https://cloud.ibm.com/schematics/workspaces/create){: external}.
    - In the **Specify Template** section:
        - **GitHub, GitLab, or `Bitbucket` repository URL** - `<provide your Terraform template Git repository URL>`.
        - **Personal access token** - `<leave it blank>`. You can click the `Open reference picker` to select your Secrets Manager key reference. For more information, see [creating a Secrets Manager instance](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&format=markdown).
3. In the Select a reference page, Select **Account**, **Service instance**, and **Secret**.
4. Click **OK**.
5. Click **Create** to create a workspace.

Observe the secret reference for an input variable, which is stored as a reference.

### Integrating Secrets Manager in variable
{: #sm-integrate-variable}
{: ui}

Follow the steps to enable Secrets Manager in Schematics to securely update the Schematics Terraform variable.

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** > [**Terraform**](https://cloud.ibm.com/automation/schematics/terraform){: external}.
3. Click your workspace to edit.
4. Click **Settings**. In **Variables** click **Edit** icon to edit the `api_key` parameters.
5. In **Edit Variable**, click the `Open reference picker` to view the Select a reference page, add **, **Service instance**, and **Secret**.
6. Click **Save** to view the secret reference parameter as `ref://secrets-manager.<REGION>.<INSTANCE_NAME>/<SECRET_GROUP>/SECRET_NAME`.

Observe the secret reference for an input variable that is stored as a reference.

## Steps to integrate Secrets Manager in Schematics by using CLI
{: #sm-cli}
{: cli}

Follow the steps to enable Secrets Manager in Schematics to securely update the Schematics Terraform.

1. [Download and install the command-line](https://cloud.ibm.com/docs/cli?topic=cli-install-ibmcloud-cli&format=markdown) and run the shared commands to target your region, create a service to service policy, create a Secrets Manager instance, reference the secrets in your Terraform code, and apply.

    ```sh
    ibmcloud login --sso
    ibmcloud target -r <region>
    ibmcloud iam service-policy-create --source-service-name schematics --target-service-instance-name <your-secrets-manager-name> --roles "Viewer,SecretReader"
    ibmcloud secrets-manager secret-create --secret-type arbitrary --name <secret-name> --payload <secret-value>
    ```
    {: pre}

2. Reference the secret in your Terraform code.

   ```terraform
    variable "my_secret" {
    default = "ref://secrets-manager.<REGION>.<INSTANCE_NAME>/<SECRET_GROUP>/SECRET_NAME"
   }
   ```
   {: pre}

3. Apply the Schematics workspace

   ```sh
   ibmcloud schematics workspace apply --id <WORKSPACE_ID>
   ```
   {: pre}


## Integrating Secrets Manager in Schematics Terraform by using API
{: #sm-api}
{: api}

Follow the steps to enable Secrets Manager in Schematics to securely connect with Schematics Terraform.

1. Follow the [steps](https://cloud.ibm.com/docs/schematics?topic=schematics-setup-api&format=markdown#cs_api) to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API.

2. Create a Secrets Manager Instance (if not already created) by using your target endpoint and IBM Cloud Resource Controller API.

   ```sh
    curl -X POST /v1/resource_instances -H "Authorization: <iam_access_token>" -d '{"name": "my-secrets-manager",
    "target": "test-eu-de",
    "resource_group": "default",
    "resource_plan_id": "<plan-id-for-secrets-manager>"
    }'
    ```
    {: pre}

3. Create a Secret in Secrets Manager by using Secrets Manager API.

   ```sh
    curl -X POST /api/v1/secrets/arbitrary  -H "Authorization: <iam_access_token>" -d '{"name": "my-token-secret","description": "Token for private Git repo","secret_group_id": "<secret-group-id>","resources": [],"payload": "your-token-value"}'
   ```
   {: pre}

4. Create a service to service IAM Policy

   ```json
    {
      "type": "service",
      "subjects": [{
        "attributes": [{
          "name": "serviceName",
          "value": "schematics"
        }]
      }],
      "roles": [
        { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" },
        { "role_id": "crn:v1:bluemix:public:iam::::role:SecretReader" }
      ],
      "resources": [{
        "attributes": [{
          "name": "serviceInstance",
          "value": "<secrets-manager-instance-id>"
        }]
      }]
    }
    ```
    {: codeblock}

5. Reference the secret in your Terraform variable file in by using Schematics workspace.

    ```terraform
     variable "git_token" {
     default = "ref://secrets-manager.<REGION>.<INSTANCE_NAME>/<SECRET_GROUP>/SECRET_NAME"
    }
    ```
    {: codeblock}

6. Update the workspace with the Terraform template to reference the secret.

    ```sh
    curl -X PATCH /v1/workspaces/{workspace_id}
    ```
    {: pre}

7. Apply the workspace with the Terraform template.

    ```sh
    curl -X POST /v1/workspaces/{workspace_id}/actions/apply
    ```
    {: pre}

## Integrating Secrets Manager in Schematics Terraform by using Terraform
{: #sm-terraform}
{: terraform}

Follow the steps to enable Secrets Manager in Schematics to securely connect with Schematics Terraform.

1. Define the [Secrets Manager Instance](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/resource_instance){: external}.
2. Create a Secret in Secrets Manager. You can use the CLI or manually create secrets. In Terraform, secrets are typically referenced, not created directly.
3. Create [IAM Service-to-Service Policy](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/iam_service_policy){: external}.
4. Reference the Secret in Terraform Variables. Replace `secret-id` with the actual ID of the secret stored in Secrets Manager.

    ```terraform
     variable "git_token" {
     default = "ref://secrets-manager.<REGION>.<INSTANCE_NAME>/<SECRET_GROUP>/SECRET_NAME"
    }
    ```
    {: codeblock}

5. Use the Schematics Terraform provider or CLI to [create your workspace](https://cloud.ibm.com/docs/schematics?topic=schematics-sch-create-wks&interface=terraform&format=markdown#create-wks-terraform) with the preceding configuration.