# Environments and variables reference

This page is the compact reference for environments, variables, their scopes, how values resolve, how they're protected, and who can manage them. For the procedures — creating environments and variables, referencing them from nodes, and testing across environments — see [Configure environments and variables](../build-ai-agents/environments-variables.md).

## Environment

An **environment** is the runtime context a flow runs in. Environments are defined at the **organization** level and shared across the organization's workspaces and AI Agents. You select an environment when you test, publish, or run a flow; the same flow can run in different environments without changing the flow. Environments are created and managed in **Settings → Environments** by an Admin or Partner.

## Variable

A **variable** is a named value — a **key** and a **value** — stored in an environment and made available to flows. Variables hold the values that differ between environments (endpoint URLs, credentials, folder IDs, thresholds), so you set them once per environment and reference them from nodes. Variables are managed in **Settings → Variables**.

## There is no separate "secret" type

All variable values are **encrypted end to end and at rest, and masked in the interface** — you reveal a value with a show/hide control rather than seeing it in plain text by default. Sensitive values such as API tokens and client secrets are simply stored as ordinary variables, which are always encrypted. There is **no separate "secret" object or "protected secret" type** to choose between: every variable is protected the same way. (In the variables list, **Global** and **Local** appear only as list filters, not as a variable type or a creatable scope.)

## Scopes

Every variable lives in an environment, but you can scope it more narrowly so it applies only where you want. The four creatable scopes map to the platform hierarchy:

| Scope | Applies to | Hierarchy level |
| --- | --- | --- |
| 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 [Core entity definitions](./core-entities.md) for how the scopes map to the hierarchy.

## Value 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):

```text
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 wins 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 before you run.

**Variable references.** A variable's value can reference another variable using `${OTHER_KEY}`. References resolve when the flow runs; circular references are detected and rejected.

**Version history and import.** 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.

## Visibility and permissions

| Role | Environments | Variables |
| --- | --- | --- |
| Admin | Full management | Full management, including revealing decrypted values and deleting variables |
| Partner | Full management | Create and update only — cannot reveal decrypted values or delete variables |
| 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).

## Where to go next

- [Configure environments and variables](../build-ai-agents/environments-variables.md) — create environments and variables, reference them from nodes, and test across environments.
- [Core entity definitions](./core-entities.md) — how environments sit in the hierarchy.
- [Start a flow run](/api/flow-executions#run-a-flow) — passing an environment ID and variables when running via the API.
- [Concepts glossary](./glossary.md) — concise definitions for every term.