Variables & Environments
How data flows between steps using flow variables, environment variables, and the scripting API.
Two Variable Systems
Atrahasis has two distinct variable syntaxes for different purposes:
| Syntax | Source | Lifetime | Use For |
|---|---|---|---|
| {{flow.varName}} | Flow Store + Extractions | Single flow run (ephemeral) | Tokens, IDs, dynamic response data |
| {{varName}} | Group Environments | Persistent (saved to disk) | Base URLs, API keys, static config |
Recommendation: Use {{flow.varName}} for any value that comes from a response (tokens, IDs, timestamps). Reserve {{varName}} for values that stay the same across runs (base URLs, API keys).
Variable Extraction
Variable extraction lets you capture values from a step's response and make them available in subsequent steps. This is the core feature that enables request chaining.
Extracting Values:
- 1Select a step and open the Processors tab
- 2Write a post-response script to capture values from the response
- 3Use at.flow.set(key, value) for ephemeral values (per-run) or at.environment.set(key, value) for persistent values (saved to disk)
- 4Reference with {{flow.varName}} (ephemeral) or {{varName}} (persistent) in any subsequent step's URL, headers, body, or params
Extraction Sources
Each extraction has a name, a source type, and an expression:
| Source | Expression | Example |
|---|---|---|
| JSON Path | Dot notation path into the response body. Supports array indexing. | data.token |
| Header | Response header name (case-insensitive) | X-Request-Id |
| Regex | Regular expression applied to the response body. First capture group is used, or the full match if no capture group. | id":(\d+) |
| Status Code | The HTTP status code (no expression needed) | 200 |
JSON Path Examples:
data.user.id → nested object access
items[0].name → array index access
meta.pagination.next → deeply nested value
token → top-level field
If the path resolves to an object or array, the value is serialized via JSON.stringify(). String values are used as-is.
Using Flow Variables
Once a variable is extracted (or set via script), reference it in any subsequent step using {{flow.varName}}:
- •URL: {{base_url}}/users/{{flow.userId}}
- •Headers: Authorization: Bearer {{flow.token}}
- •Body: {"parent_id": "{{flow.parentId}}"}
- •Params: cursor={{flow.nextCursor}}
- •Assertions: response body data.id equals {{flow.userId}}
Note: Variables are resolved at runtime, just before each step executes. If a variable hasn't been extracted yet (e.g., the source step hasn't run), the placeholder {{flow.varName}} remains as-is in the request.
at.flow Scripting API
In pre-request and post-response scripts, you can use the at.flow API to share data between steps programmatically.
Available Methods:
Post-script Example (after login step):
const data = at.response.json();
at.flow.set("token", data.token);
at.flow.set("userId", String(data.user.id));
at.flow.set("role", data.user.role);
Pre-script Example (before a subsequent step):
if (at.flow.has("token")) {
at.request.setHeader("Authorization", "Bearer " + at.flow.get("token"));
}
When to use at.flow vs at.environment: Use at.flow.set() for values needed only during the current run (tokens, session IDs). Use at.environment.set() for values that should persist across runs (saved to disk).
Variable Resolution Order
When a step is about to execute, variables are resolved in a specific order:
{{varName}} (Environment Variables):
- 1. Live environment context (values set via at.environment.set() in scripts)
- 2. Static environment variables (defined in the environment manager)
{{flow.varName}} (Flow Variables):
- 1. Flow Store (values set via at.flow.set() in scripts)
- 2. Extracted variables (from previously executed steps)
Note: Environment variables ({{varName}}) are resolved first, then flow variables ({{flow.varName}}). This means you can mix both in the same field: {{base_url}}/users/{{flow.userId}}
Flow Environments
Each Flow Group can have its own set of environments (e.g., dev, staging, prod) with environment-specific variables. These are referenced using {{varName}} (without the flow. prefix).
Setting Up Environments:
- 1Right-click a Flow Group in the sidebar → Environments
- 2Add environments (e.g., "Development", "Staging", "Production")
- 3Define variables for each environment (e.g., base_url, api_key)
- 4Select the active environment from the dropdown in the Action Bar
Example Environment Setup:
| Variable | Development | Staging | Production |
|---|---|---|---|
| base_url | http://localhost:3000 | https://staging.api.com | https://api.com |
| api_key | dev-key-123 | stg-key-456 | prod-key-789 |
With this setup, {{base_url}}/api/users resolves to http://localhost:3000/api/users in Development and https://api.com/api/users in Production.
Note: Values set via at.environment.set(key, value) in scripts are persisted to disk and update the active environment permanently. Use this for values that should survive across flow runs.
Variable Sources
Every flow environment variable has a source that decides where its value lives and how it is loaded at runtime. There are three sources, and they are mutually exclusive on a per-variable, per-environment basis.
| Source | Where the value lives | Best for |
|---|---|---|
| Manual | Plain text on disk inside the flow group's environment file. Visible to anyone with file access and to git history if committed. | Non-sensitive config: base URLs, feature flags, test usernames. |
| OS Secret | OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). The disk file only stores { key, secret: true, source: "os" } — no value. | Anything sensitive you control locally: personal API keys, dev tokens, test passwords. |
| Vault | External secret manager (HashiCorp Vault). Only the connection name + path + key are stored locally; the value is fetched at runtime after you log in. | Team-shared secrets governed by your security/SRE pipeline: production credentials, rotated tokens, customer API keys. |
Mutually exclusive per environment: When you mark a variable as Secret, the per-environment source dropdown is disabled — every environment writes its value to the OS keychain. When any environment of a variable is bound to Vault, the Secret checkbox is hidden, since Vault already handles secret storage on its own.
OS Secret Variables
Marking a variable as Secret in the Add/Edit Variable modal switches it from disk-backed plain text to OS keychain–backed storage. This is the simplest way to keep sensitive values out of files, screenshots, and git diffs while still letting you reference them in any step via {{varName}}.
How OS secrets work:
- •Per-environment values: Each environment (dev, staging, prod) gets its own keychain entry, so you can store a different secret value per env without mixing them.
- •Masked input: The value field switches to a password input with an eye toggle so you can briefly reveal what you typed.
- •Disk hygiene: The value is never written to the environment file. Only the metadata (key name + secret flag + source) is persisted. Safe to commit.
- •Runtime read: When the flow runs, Atrahasis reads the value back from the OS keychain right before sending each request, merges it into the variable map, and substitutes it into URLs, headers, body, and auth fields.
- •Cleanup: Deleting the variable, deleting the environment, or unchecking Secret removes the matching keychain entry so nothing is left dangling.
Auth use case: The cleanest way to wire a Bearer token, API key, or Basic password into your flow. Mark api_token as Secret, drop {{api_token}} into the Auth tab, and the value never leaves the OS keychain except at request-build time.
Vault Integration
For secrets that should be governed centrally rather than stored on individual machines, Atrahasis can pull values directly from HashiCorp Vault. Connect once, then bind any environment variable to a vault path/key.
Setup & usage:
- 1Configure a Vault Connection from the Vault settings: name it, set the URL, and pick an auth method (token or userpass).
- 2In the Add/Edit Variable modal, expand the per-environment source dropdown and pick the connection name (instead of Manual).
- 3Provide the vault path (e.g., secret/data/atrahasis/dev) and the key inside that secret object (e.g., api_token).
- 4The first time you run a flow that uses a vault-bound variable, Atrahasis opens a vault login modal. The session is cached in the OS keychain so subsequent runs do not re-prompt until the session expires.
What is stored where:
- •On disk (environment file): Just the binding — connection name, vault path, and key. Safe to commit.
- •In OS keychain: Vault connection settings (URL, auth method) and the active session token, scoped per connection.
- •In Vault: The actual secret value. Atrahasis reads it on demand right before each flow run and never persists it locally.
Vault failures don't fail silently: If a vault path/key cannot be resolved at run time, Atrahasis surfaces the failure in the run results with the exact connection name and key so you can fix the binding instead of debugging a phantom missing variable.
Secret vs Vault — Which One?
Both keep sensitive values off disk, but they answer different questions.
| Question | Use OS Secret | Use Vault |
|---|---|---|
| Who manages this value? | You, on your own machine | Your team / SRE / security pipeline |
| Should rotation be central? | No — rotate it locally when you want | Yes — Vault rotates, Atrahasis picks up the new value automatically |
| Need to share with teammates? | No — values are local to your keychain | Yes — anyone with vault access reads the same value |
| Have a HashiCorp Vault server? | Not required | Required |
Variable Types Comparison
| Feature | Environment {{varName}} | Extraction {{flow.varName}} | Flow Store at.flow.set() |
|---|---|---|---|
| Defined | Before execution | During execution (post-response) | During execution (scripts) |
| Scope | All flows in the group | Current flow run | Current flow run |
| Persistence | Saved to disk | Ephemeral (per iteration) | Ephemeral (per iteration) |
| Referenced As | {{varName}} | {{flow.varName}} | {{flow.varName}} |
| Priority | at.environment.set() > static | Fallback if no Flow Store value | Highest (overrides extractions) |
| Best For | Base URLs, API keys, static config | Simple response values | Computed/transformed values |