> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bentralabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables and secrets

> Give workflow steps configuration and credentials as environment variables, from reusable collections or the workflow itself.

Variables reach a workflow's steps as environment variables. A variable named `AWS_REGION` is `$AWS_REGION` in every step. Mark a variable **secret** for passwords, tokens and keys.

Variables come from two places:

| | Variable collections | Workflow variables |
| - | - | - |
| What | A named, reusable set of variables | Variables that belong to one workflow |
| Where | **Settings → Variable Collections** | The workflow's **Variables** tab |
| Used by | Every workflow it's attached to | That workflow only |
| Owned by | A workspace, whose members manage it | The workflow |

Use a collection for anything several workflows share, such as cloud credentials for an environment. Use workflow variables for values specific to one workflow, or to override a collection value.

## Variable collections

### Create a collection

**1. Open Variable Collections**

Go to **Settings → Variable Collections**.

**2. Name it**

Enter a **Collection name**, for example `AWS prod`, and an optional **Description**.

**3. Choose the owner**

Under **Owned by**, pick the workspace that owns the collection. Its members manage the collection, whoever created it.

**4. Share it (optional)**

Under **Also share with**, tick the workspaces whose workflows may use it, or **Every workspace in the organization**. Workflows there can attach the collection but can't change it.

**5. Create it and add variables**

Click **Create collection**. Then open it with **Manage** and click **Add Variable** for each variable.

### Who can manage collections

* **Organization owners and admins** can create and change any collection, and share with every workspace or the default workspace.
* **Members** can create collections owned by a workspace they belong to, except the default workspace. They can change any collection their workspaces own, whoever created it.
* Everyone sees the collections usable in their workspaces: owned by, shared with, or shared with every workspace. A collection shared with you shows **View** instead of **Manage**.

If you can't create collections, join a workspace other than the default one, or ask an admin. See [Members and groups](https://docs.bentralabs.com/guides/members-and-groups.md).

### Share, move and delete

A collection's **Permissions** card shows who owns it and which workspaces can use it.

* **Share** with one more workspace, or **Share with every workspace**. Stop sharing from the list.
* **Move** gives the collection to another workspace. The old workspace keeps access while its workflows still have the collection attached.
* Bentra won't stop sharing with a workspace while a workflow there still has the collection attached. Detach it from those workflows first.
* **Delete** removes the collection and its variables and detaches it from every workflow.

The **Attached Workflows** card shows which workflows use the collection.

### Attach a collection to a workflow

Open the workflow's **Variables** tab and click **Attach Collection**. You can attach collections owned by the workflow's workspace, shared with it, or shared with every workspace.

You need the workflow's **Manage variables** permission, which workflow Admins and Writers have.

## Workflow variables

On the workflow's **Variables** tab, under **Workflow Variables**:

* **Add Variable** adds one variable.
* **Import from JSON** adds several at once from a flat JSON object such as `{"REGION": "eu-west-1", "BUCKET_PREFIX": "acme-"}`. Imported values are never secret; mark secrets one by one.

## Variable settings

Every variable, in a collection or on a workflow, has:

| Setting | Meaning |
| - | - |
| **Key** | Letters, digits and underscores, starting with a letter or underscore. Unique within its collection or workflow. |
| **Value** | The value. |
| **Secret** | Encrypt the value and never show it again. See [Secrets](#secrets). |
| **Treat as JSON** | The value is a list, object, number, `true`/`false` or `null` written as JSON, not a string. See [JSON variables](#json-variables). |

## When names clash

The same key can be defined in several collections and on the workflow. A run gets exactly one value per key:

1. The workflow's own variables win over every collection.
2. Among attached collections, a later one wins over an earlier one.

Collections are applied in the order shown on the **Variables** tab, lowest number first. Drag a collection, or use **Move Up** and **Move Down** in its menu, to change the order.

A workflow variable that overrides a collection value shows an **overrides collection** badge. Bentra compares only keys, so finding clashes never reads a secret.

Variables also override a form field with the same `id`: a variable `REGION` replaces the form's `region` answer in `$REGION`. Give form fields and variables different names unless you mean it.

### Variables for a single run

When you start a job with **Trigger Run**, add **Ad-hoc Variables**: key/value pairs for this run only. Steps get them as environment variables and in `bento_inputs.json`, like form answers.

Through the API, pass `runtime_variables` to [`POST workflows/{id}/runs/trigger/`](https://docs.bentralabs.com/reference/api/runs). The run page's **Inputs** panel shows them as **Runtime variables**.

## Secrets

Mark a variable **Secret** when its value is sensitive.

* **Write-only.** After you save it, nobody can read the value back in the UI or the API. It's shown as `••••••••`. To change a secret, enter a new value; leaving the value blank when editing keeps the existing one.
* **Encrypted at rest.** Secret values are encrypted with a key specific to your organization.
* **Masked in logs.** If a step prints a secret value, it's replaced with `***` in the run's logs. Values shorter than 4 characters aren't masked, and each line of a multi-line secret is masked separately.
* **Decrypted only for runs.** Bentra decrypts a secret only to hand it to the runner executing a run. A run only decrypts the values it uses, so a broken secret that is overridden never fails a run.

> [!WARNING]
>
> Masking catches the exact value only. A secret that a step transforms (base64, URL-encoded, split up) is not masked. Don't print secrets.

> [!TIP]
>
> Keep secrets in variables, not in workflow files. Anyone who can view a workflow can read its files.

## How variables reach steps

* Each variable is an environment variable in every step, named after its key in upper case.
* A **Treat as JSON** variable arrives as compact one-line JSON text.
* Every variable is also written to `bento_variables.json` in the workspace, with JSON variables as real JSON values. Its path is in `$BENTRA_VARIABLES`. The file is readable only by the user running the steps, because it includes secret values.
* `bento.env` holds form inputs and system variables, not your variables.

See [Inputs and environment variables](https://docs.bentralabs.com/reference/workflow-syntax.md#inputs-and-environment-variables) for the full list of what a step receives.

### JSON variables

Use **Treat as JSON** for structured values, such as a list of allowed regions:

```json theme={"theme":{"light":"github-light","dark":"night-owl"}}
["eu-west-1", "eu-central-1"]
```

Read it in a step from the file, where it's a real list:

```bash theme={"theme":{"light":"github-light","dark":"night-owl"}}
jq -r '.ALLOWED_REGIONS[]' "$BENTRA_VARIABLES"
```

Bentra checks the value is valid JSON when you save it. If a JSON variable doesn't parse when a run starts, the run fails during setup.

> [!NOTE]
>
> Secret masking, JSON variables and `bento_variables.json` need runner **0.10.0** or newer. See [Install a runner](https://docs.bentralabs.com/runners/install.md#versions).

## API and MCP

Collections, sharing, workflow variables and attaching collections are all available through the [Variables API](https://docs.bentralabs.com/reference/api/variables.md) and the [MCP server](https://docs.bentralabs.com/ai/mcp-server.md). Prefer entering secret values in Bentra rather than through an agent, so the value doesn't pass through the conversation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.