# Configure environments and variables

Environments and variables let the same flow run in different contexts without changing the flow itself. An **environment** is the context a flow runs in; **variables** hold the values that differ between those contexts — endpoint URLs, credentials, folder IDs, thresholds — so you set them once per environment and reference them from your nodes.

A typical pattern: build and test a flow against a test environment with sandbox settings, then publish and run it in a production environment where the same variables resolve to live settings. The flow doesn't change — only the environment does.

## Environments

An environment is defined at the **organization** level and is shared across the organization's workspaces and AI Agents. Each flow run happens in a chosen environment.

**The environment selector (builder).** While building, the builder includes an environment selector. The environment you choose is the one **Run Draft** executes against, so you can test a draft with one environment's configuration and switch to another to test different settings. See [Test and debug a draft](./test-debug-draft.md).

**Managing environments.** Environments are created and managed in **Settings → Environments**. This requires the **Admin** or **Partner** role.

## Variables

A variable is a named value — a **key** and a **value** — stored in an environment and made available to your flows. Variables are managed in **Settings → Variables**.

**Values are protected.** Variable values are encrypted end-to-end and at rest, and are masked in the interface. You reveal a value with a show/hide control rather than seeing it in plain text by default. There is no separate "secret" object: sensitive values such as API tokens and client secrets are simply stored as variables, which are always encrypted.

### Scopes

Although every variable lives in an environment, you can scope it more narrowly so it only applies where you want. When you create a variable you choose its scope, and for the narrower scopes you select the specific workspace, AI agent, or flow it belongs to.

| Scope | Applies to | In the platform hierarchy |
| --- | --- | --- |
| Environment | Everything running in that environment | Organization-level context |
| Workspace | Flows in a specific workspace | Workspace |
| AI Agent | Flows in a specific AI Agent | AI Agent |
| Flow | A single flow | Flow |

See [Platform hierarchy](../onboarding/platform-hierarchy.md) for how organizations, workspaces, and AI Agents relate.

### Creating or editing a variable

1. Go to **Settings → Variables** and choose the **Environment**.
2. Add or edit a variable: enter the **key** and **value**.
3. Choose the **Scope**. For Workspace, AI Agent, or Flow, also select the specific workspace, AI agent, and flow as required.
4. Save. The value is encrypted before it's stored.

Variables keep a **version history**, so you can see how a value changed over time, and you can **import** multiple variables at once rather than entering them one by one.

**Referencing other variables.** A variable's value can reference another variable using `${OTHER_KEY}`. References are resolved when the flow runs, and circular references are detected and rejected.

## Using variables in nodes

Reference a variable from a node's configuration field instead of typing a constant. In fields that accept an expression, type `$` to browse the values available — including variables — and select the one you want. At run time the reference resolves to the variable's value for the current environment and the most specific scope that defines it.

This is how connection details stay out of the flow itself. For example, an [App integration node](./app-integration-nodes.md) points its endpoint and authorization header at variables, so the flow works in any environment where those variables are set.

## Runtime resolution

When a flow runs, each variable reference resolves to a single value based on the chosen environment and the variable's scope. More specific scopes win over broader ones, in this order (highest to lowest precedence):

**Flow → AI Agent → Workspace → Environment**

So if the same key is defined at both the environment scope and the flow scope, the flow-scoped value is used for that flow. If only the environment-scoped value exists, that one applies. The variables interface includes a **resolution view** that previews which value wins for a given context, so you can confirm what a flow will actually use before running it.

## Permissions

| Role | Environments | Variables |
| --- | --- | --- |
| Admin | Full management | Full management, including revealing decrypted values |
| Partner | Full management | Create and update variables; cannot delete them or view decrypted values |
| Reviewer | No access | Not part of the build workflow |

Managing environments and variables happens in Settings and is an Admin or Partner activity. See [Users and access](../onboarding/users-access.md).

## Example: testing the same flow across environments

A claims flow writes to Guidewire and references two variables — `GUIDEWIRE_ENDPOINT` and the authorization token — rather than hard-coded values.

1. In **Settings → Variables**, an Admin sets these variables in a **test** environment to point at the Guidewire sandbox, and in a **production** environment to point at the live system.
2. While building, the builder selects the **test** environment in the environment selector and clicks **Run Draft**. The flow resolves `GUIDEWIRE_ENDPOINT` to the sandbox and writes there, so testing never touches production.
3. Once the flow is validated, it is published. When it runs in **production**, the same references resolve to the live settings — with no change to the flow.

To scope a value to just one flow during testing, define the variable at the **Flow** scope; it overrides the environment-scoped value for that flow only.

## Where to go next

- [Test and debug a draft](./test-debug-draft.md) — use the environment selector and Run Draft.
- [Drafts and publishing](./drafts-publishing.md) — move a validated draft to production.
- [App integration nodes](./app-integration-nodes.md) — reference connection variables from nodes.
- [Platform hierarchy](../onboarding/platform-hierarchy.md) — how environments, workspaces, and AI Agents relate.
- [Users and access](../onboarding/users-access.md) — who can manage environments and variables.