Skip to content

Using Secrets

If a user does not have access to a referenced secret, the workflow will fail.

Configuring secrets

Use the Create or update secret API (PUT /secrets/{key}) or go to Definitions > Secrets, select + Add secret, and enter the following parameters:

Parameter Description Required/Optional
Secret name A unique name for the secret. Used to reference the secret in workflow definitions. Can contain only letters, numbers, underscores, and hyphens. Required.
Secret value The value to be stored as secret. Can be a plain string or a JSON object. Required.

Using secrets in workflow

To use a secret in a workflow, use the following expression:

${workflow.secrets.secret_name}

Here, secret_name is the name of the secret saved in Conductor. This expression dynamically retrieves the secret value during workflow execution, ensuring it is not exposed directly in the workflow definition.

If the secret value is a JSON object, you can access individual fields using dot notation:

${workflow.secrets.secret_name.field_name}

For example, if a secret named db-credentials has the value {"username": "admin", "password": "secret123"}, you can reference the username as ${workflow.secrets.db-credentials.username}.

Updating secrets

Updating a secret does not require changing or redeploying workflow definitions, since workflows reference the secret name rather than its value. Keep the secret name stable and rotate the value stored behind it.

Use the same Create or update secret API with the existing secret name, or go to Definitions > Secrets, select the secret, enter the new value in Secret value, and select Edit.

Updating secrets in a workflow

Use the Update Secret task when secrets need to be replaced programmatically within a workflow; for example, when an access token expires and must be rotated automatically.

The task requires the following input structure:

{
  "_secrets": {
    "secretKey": "my-secret-name",
    "secretValue": "${workflow.secrets.new-token-secret}"
  }
}

If _secrets, secretKey, or secretValue are missing or empty, the task terminates the workflow immediately.

Examples

Using a secret in an HTTP task

Suppose you have a secret named sampletask-api-token. Here is an example of how to use this secret in a workflow definition:

// workflow definition
{
  "name": "sample_task_http",
  "taskReferenceName": "sample_task_http",
  "inputParameters": {
    "http_request": {
      "uri": "https://orkes-api-tester.orkesconductor.com/api",
      "method": "GET",
      "connectionTimeOut": 3000,
      "readTimeOut": 3000,
      "accept": "application/json",
      "contentType": "application/json",
      "headers": {
        "Authorization": "Bearer: ${workflow.secrets.sampletask-api-token}"
      }
    }
  },
  "type": "HTTP"
}

When this workflow runs, the expression ${workflow.secrets.sampletask-api-token} will be dynamically replaced with the secret value, provided the user running the workflow has READ permission over the secret.

Using a JSON secret with dot notation

Suppose you have a secret named db-credentials with the following JSON value:

{
  "username": "admin",
  "password": "secret123"
}

Reference individual fields in a task input using dot notation:

{
  "name": "db_query_task",
  "taskReferenceName": "db_query_task",
  "inputParameters": {
    "username": "${workflow.secrets.db-credentials.username}",
    "password": "${workflow.secrets.db-credentials.password}",
    "query": "SELECT * FROM orders WHERE status = 'pending'"
  },
  "type": "SIMPLE"
}