---
name: secrets-manager-custom-credentials
title: Creating custom credentials secrets
description: The custom credentials secret type enables IBM Cloud® Secrets Manager users to securely manage credentials for external systems (such as Artifactory or PagerDuty) through Secrets Manager APIs and integrations. To create these secrets, you deploy an IBM Cloud® Code Engine job that acts as a bridge between Secrets Manager and the external service. These jobs run on a fixed schedule and manage credentials asynchronously by using secret tasks.
last-updated: 2026-04-22
---

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

# Creating custom credentials secrets
{: #custom-credentials}

The custom credentials secret type enables IBM Cloud® Secrets Manager users to securely manage credentials for external systems (such as Artifactory or PagerDuty) through Secrets Manager APIs and integrations. To create these secrets, you deploy an  IBM Cloud® Code Engine job that acts as a bridge between Secrets Manager and the external service. These jobs run on a fixed schedule and manage credentials asynchronously by using [secret tasks](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secret-tasks&format=markdown).
{: shortdesc}

The process for creating custom credentials is asynchronous by design. When a new secret is added, it initially enters a **pre-activation** state. If the secret is successfully created in the external credentials provider, its state automatically becomes **active** within Secrets Manager.

The custom credentials secrets creation process is asynchronous. After a secret is added, it begins in `pre-activation` state and if created successfully in the credentials provider, its state changes to `active` in Secrets Manager.
{: note}

## Before you begin
{: #before-custom-credentials}

Before you get started, make sure that you have:
- The required level of access. To create or add secrets, you need the [**Writer** service role or higher](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam&format=markdown).
- Configured your instance to create custom credentials secrets by [creating a Code Engine job and custom credentials engine configuration](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-custom-credentials-prepare&format=markdown).

## Creating a custom credentials secret in the console
{: #custom-credentials-secret-ui}
{: ui}

To add a secret:

1. In the **Secrets** table, click **Add**.
2. From the list of secret types, click the **Custom credentials** tile.
3. Click **Next**.
4. Add a name and description to easily identify your secret.
5. Select the [secret group](#x9968962){: term} that [you have previously created](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-custom-credentials-config&interface=ui&format=markdown#custom-credentials-config-before-begin).
6. Optional: Add labels to help you to search for similar secrets in your instance.
7. Optional: Add metadata to your secret or to a specific version of your secret.
    1. Upload a file or enter the metadata and the version metadata in JSON format.  
8. Click **Next**.
9. Select the custom credentials engine configuration to use for this secret.
10. Enter the required values under **Parameters**.
11. Click **Next**.
12. Optional: Enable least duration and automatic rotation of your secret.
13. Click **Next**.
18. Review the details of your secret. 
19. Click **Add**.

You can change the value of the parameters later. The change takes place after a new secret version is created. You cannot add or subtract new parameters without creating a new configuration.
{: note}

## Viewing and updating secret details in the console
{: #custom-credentials-view-update-ui}
{: ui}

As with [any other secret](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-updating-secret-metadata&format=markdown), you can access your secret details by clicking the click the **Actions** menu ![Actions icon](../icons/actions-icon-vertical.svg) > **Details**. From the details screens, you can learn about:

* [Accessing secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-access-secrets&format=markdown)
* [Deleting secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-delete-secrets&format=markdown)
* [Automatically rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-automatic-rotation&format=markdown)
* [Manually rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manual-rotation&format=markdown)
* [Updating secret version metadata](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-updating-secret-version&format=markdown)
* [Managing secrets versions](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history&format=markdown)

## Creating a custom credentials secret from CLI
{: #custom-credentials-secret-cli}
{: cli}

Before you begin, [follow the CLI docs](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli&format=markdown) to set your API endpoint.

To create a custom credentials secret by using the Secrets Manager CLI plug-in, run the [**`ibmcloud secrets-manager secret-create`**](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli&format=markdown#secrets-manager-cli-secret-create-command) command. 

```sh 
ibmcloud secrets-manager secret-create --secret-type custom_credentials --secret-name "example-custom-credential-secret" --secret-description "Description of my custom credential secret" --secret-rotation '{"auto_rotate": true,"interval": 30,"unit": "day"}' --custom-credentials-parameters '{"my_input_parameter":"my_param_value"}' --custom-credentials-configuration '{"my_custom_credential_config"}' --secret-custom-metadata '{"metadata_custom_key": "metadata_custom_value"},"version_custom_metadata": {"custom_version_key": "custom_version_value"}}'
```
{: pre}


## Creating a custom credentials secret using API
{: #custom-credentials-secret-api}
{: api}

You can create a custom credential programmatically by calling the Secrets Manager API. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

You can store metadata that are relevant to the needs of your organization with the `custom_metadata` and `version_custom_metadata` request parameters. Values of the `version_custom_metadata` are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.


```sh
curl -X POST 
    -H "Authorization: Bearer {IAM_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "example-custom-credential-secret",
      "description": "Description of my custom credential secret",
      "secret_type": "custom_credentials",
      "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
      "labels": [
        "dev",
        "us-south"
      ],
      "rotation": {
        "auto_rotate": true,
        "interval": 30,
        "unit": "day"
      },
      "configuration": "my_custom_credential_config",
      "parameters": {
        "user_name": "username",
        "scope": "admin"
      },
      "custom_metadata": {
        "metadata_custom_key": "metadata_custom_value"
      },
      "version_custom_metadata": {
        "custom_version_key": "custom_version_value"
      }
    }'
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets" 
```
{: codeblock}
{: curl}

## Creating a custom credentials secret by using Terraform
{: #custom-credentials-secret-terraform}
{: terraform}

You can create custom credentials secrets programmatically by using Terraform for Secrets Manager.
The following example shows a configuration that you can use to create a custom credentials secret.

Creating custom credentials secrets is an asynchronous process that can potentially take a long time depending on the use-case, therefore when planning to use Terraform potential delays should be considered.
{: note}

```terraform
resource "ibm_sm_custom_credentials_secret" "sm_custom_credentials_secret" {
  instance_id   = ibm_resource_instance.sm_instance.guid
  region        = "us-south"
  name 			= "secret-name"
  secret_group_id = ibm_sm_secret_group.sm_secret_group.secret_group_id
  custom_metadata = {"key":"value"}
  description = "Extended description for this secret."
  labels = ["my-label"]
  configuration = "my_custom_credentials_configuration"
  parameters {
    int_values = {
        example_param_1 = 17
    }
    string_values = {
        example_param_2 = "str2"
        example_param_3 = "str3"
    }
    bool_values = {
        example_param_4 = false
    }
  }
  rotation {
      auto_rotate = true
      interval = 3
      unit = "day"
  }
  ttl = "864000"
}
```

Leverage the Terraform IBM Modules (TIM) for [Secrets Manager Custom Credentials Engine](https://registry.terraform.io/modules/terraform-ibm-modules/secrets-manager-custom-credentials-engine/ibm/latest){: external} to define custom credentials as code with repeatable configurations. Get started with [Terraform IBM Modules](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-about-tim&format=markdown).
{: tip}