---
url: /services/workflow/secrets.md
description: >-
  Pass SecretValue parameters securely to orchestrated services by defining a
  $secrets input variable in your workflow configuration.
---

# Using Secrets in Workflow Services

This guide explains how to securely pass secrets to orchestrated services within your workflow, ensuring sensitive information like API tokens and credentials are handled safely.

## Overview

When orchestrating services that require secret inputs, workflow services provide a special mechanism to securely pass these sensitive values without exposing them in logs or workflow variables.

## How Secrets Work in Workflows

In workflow services, you can orchestrate services that require `SecretValue` parameters by:

1. **Defining a `$secrets` input variable** in your orchestration configuration
2. **Mapping workflow input fields to orchestrated service secret parameters**
3. **The platform automatically handles** the secure injection of secret values

This approach maintains security while allowing workflows to coordinate services that need sensitive credentials.

## Basic Secret Mapping Syntax

To pass secrets to an orchestrated service, define a `$secrets` input variable with a mapping structure:

```python
{
    "ibm_token": secret_value("field_name_in_json_input")
}
```

**Structure Explanation**:

* **Key** (`ibm_token`): The secret parameter name expected by the orchestrated service
* **Value** (`secret_value("field_name_in_json_input")`): Maps to a field in the workflow's JSON input where the secret value will be provided

## Example: Orchestrating a Service with Secrets

### Scenario

You have a workflow that orchestrates a quantum service requiring an IBM Quantum token for authentication.

### Orchestrated Service

The target service expects a secret parameter:

```python
from qhub.commons.secret import SecretValue

def run(circuit_data: dict, ibm_token: SecretValue) -> dict:
    """
    Executes a quantum circuit on IBM Quantum hardware.
    """
    token = ibm_token.unwrap()
    # Use token for IBM Quantum API authentication
    ...
```

### Workflow Service

Let's imagine we just use a workflow service to orchestrate the service from above, simply like so:

```
○ → [Orchestrated Service] → ●
```

### Workflow Input JSON

As the `Orchestrated Service` requires a `circuit_data` dictionary and an
`ibm_token` secret, we could define to expose those parameters in the workflow input JSON like this:

```json
{
  "circuit_data": {
    "qubits": 5,
    "gates": ["H", "CNOT"]
  },
  "$secrets": {
    "ibm_api_token": "your-secret-ibm-token-here"
  }
}
```

### Input Mapping

Go to the input mapping of the `Orchestrated Service` in the workflow editor.

Click **+** for each input mapping:

| Local variable name | Variable assignment value                        | Description                                                                                |
|---------------------|--------------------------------------------------|--------------------------------------------------------------------------------------------|
| `circuit_data`      | `circuit_data`                                   | Direct mapping of the workflow input to the orchestrated service.                          |
| `$secrets`          | `{ "ibm_token": secret_value("ibm_api_token") }` | Map secret `ibm_api_token` from workflow input to `ibm_token` of the orchestrated service. |

## How It Works Under the Hood

1. **Workflow receives input** with secret values in designated JSON field (`$secrets`)
2. **Platform extracts secret values** from the specified input fields (`secret_value("field_name_in_json_input")`)
3. **During execution**, the actual secret values are stored securely in a secure storage system designed for sensitive data
4. **Secrets are injected** as environment variables into the orchestrated service runtime
5. **Orchestrated service receives** `SecretValue` objects that wrap the sensitive data
6. **After execution**, secret values are purged from the secure storage system
7. **Security is maintained** throughout the orchestration chain