> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/welcome-to-stackai/security-and-governance/security-in-stackai/environment-variables.md).
# Environment Variables
Environment variables store sensitive values like API keys and tokens outside your workflow. This keeps secrets encrypted and out of node settings.
{% hint style="info" %}
Use environment variables for secrets and stage-specific configuration.
{% endhint %}
### Why use environment variables
Environment variables keep credentials out of your workflow.
They also let you use different values in development, staging, and production without editing your nodes each time.
### What you’ll do
* Create an environment and add variables.
* Link an environment to a project.
* Reference variables inside a workflow.
* Understand runtime resolution and access control.
### Create an environment and add variables
Go to **Settings** → **Environments** in your org sidebar.
An environment is a named container for variables.
You can create multiple environments for different teams, projects, or security boundaries.
Inside an environment, click **Add Variable**.
Fill in these fields:
* **Key** — the identifier used in your workflow, like `OPENAI_API_KEY`. Use underscores only.
* **Development Value** — the value used in the development stage.
* **Staging Value** — the value used in the staging stage.
* **Production Value** — the value used in the production stage.
All values are encrypted at rest.
Click **Save** to store the variable. The key stays visible. Values stay masked by default.
### Link an environment to your project
Variables do not apply to a project automatically.
Open your project in the Flow Editor.
Find the environment selector in the project settings panel or version toolbar. Then choose the environment you want.
The linked environment determines which values resolve at runtime. Only one environment can be linked to a project version at a time.
If you switch environments, the next run uses the new values.
### Reference variables inside a workflow
Use the variable picker anywhere you want to insert an environment variable.
In any text field, open the variable picker and choose the variable you want.
The picker includes:
* **System Variables** — built-in values used during a run
* **Environment Variables** — variables from the linked environment
Click a variable chip to insert it inline.
After insertion, the variable appears as a chip in the field. The raw value does not appear in the editor.
You can use the picker in prompts, system messages, headers, URLs, request bodies, code nodes, and conditions.
### How variables resolve at runtime
When a workflow run starts, StackAI looks up the environment linked to that project version. It then checks the current stage and decrypts the matching value for each variable.
Values resolve before any node runs. By the time an API call or LLM node executes, the selected variable has already been replaced with the real value.
Keep these rules in mind:
* The workflow must be **Published** for environment variables to resolve in live runs.
* If a referenced key does not exist in the linked environment, the run fails.
* Changing the linked environment affects the next run immediately.
{% hint style="warning" %}
Draft saves do not trigger environment variable resolution in live runs.
{% endhint %}
### Access control by role
Your org role settings control who can view or change environment variables.
Go to **Organization** → **Environments** → **Permissions** to manage access.
| Role | Access |
| ---------- | ------------------------------------------------------------ |
| **Viewer** | See variable keys only. Values stay masked. |
| **Editor** | View keys, create variables, and update values. |
| **Admin** | Full control, including deleting variables and environments. |
Editors can update values, but they cannot delete environments.
### Best practices
* **Do not hardcode secrets.** Secrets pasted into node fields stay visible to anyone with project access.
* **Use separate values per stage.** Point development and staging to test systems. Reserve production credentials for production only.
* **Name keys consistently.** A format like `SERVICE_ENV_KEY` keeps secrets easy to scan.
* **Review access regularly.** Remove access when a teammate no longer needs it.
* **Publish before live testing.** Publish the workflow before testing against real services.
* **Separate environments by security boundary.** Do not reuse one environment across unrelated projects.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.stackai.com/welcome-to-stackai/security-and-governance/security-in-stackai/environment-variables.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.