Where Data Lives
Put each value where its lifetime, sensitivity, and purpose fit. App connections authorize a service, workspace assets are shared across workflows, Custom Variables belong to one run, and literal values belong to one field.
Choose the right home
| What you are storing | Put it here | Scope and lifetime | How a workflow uses it |
|---|---|---|---|
| Permission to act in Slack, Google Sheets, Salesforce, or another catalog app | App connection | Shared in the workspace until disconnected or reauthorized | Select the account from the app step’s Account dropdown |
| API key, token, signing key, or password used in a field | Secret | Shared in the workspace; encrypted and not shown again after saving | {{ $secret.KEY }} |
| Non-sensitive setting used by several workflows | Workspace variable | Shared in the workspace; editable in place | {{ $var.KEY }} |
| Intermediate value, flag, or calculation for one run | Custom Variables step | One step in one workflow run | {{ N.variable_name }} |
| Template, reference document, data set, or other reusable asset | File | Shared in the workspace until deleted | Select it in a file field or use {{ $file.<id> }} |
| Fixed text or number used by one field | Literal field value | Stored in that workflow field | Type it directly, such as approved or 30 |
App connection: permission to use a service
Use a connection when a catalog app step needs to act on an account. The connection holds the authentication required by that service; the step holds the action, destination, and mapped data.
For example, a Google Sheets step selects a connected account from Account, then selects a spreadsheet and worksheet. Do not copy that account’s OAuth token into a secret or a field. The connection manages the service authorization and can be reused by other app steps in the workspace.
Use a secret instead when you are configuring an HTTP Request or another field that explicitly asks for a token rather than offering an Account dropdown.
Secret: sensitive text used by a field
Store an API key, bearer token, webhook signing key, or password as a secret when a workflow field must send the value itself.
{{ $secret.BILLING_API_KEY }}A secret’s value is encrypted at rest and is not displayed again after you save it. Rotate it by deleting and recreating the same key; existing references keep the same name.
Do not paste credentials directly into an HTTP header, URL, prompt, or code block. A literal stays visible with the workflow and does not receive the same secret handling.
Connection or secret? If the app step offers an Account dropdown, use
a connection. If a field needs the credential text itself, store that text as
a secret and reference it with $secret.
Workspace variable: a shared, non-sensitive setting
Use a workspace variable for a value that several workflows should read by the same name and that workspace members may see, such as a region, support address, tax rate, or environment base URL.
{{ $var.REGION }}
{{ $var.TAX_RATE }}Variables are editable in place and are not fixed when a run starts. Each step reads them when its placeholders are resolved, so a later step can see a value changed while the run is under way. References resolved together within one step use the same fetched value set.
Use a secret instead if exposing the value would grant access or reveal sensitive information. Use a literal instead if only one field needs the value and central updates would add no benefit.
Custom Variables: values scoped to one run
The Custom Variables step creates named fields for later steps in the same run. It is useful for an intermediate calculation, a flag chosen on one branch, or a value assembled once and read later.
If step 3 defines requires_approval, downstream steps read:
{{ 3.requires_approval }}A Custom Variables value belongs to the step that created it and disappears when the run ends. The next run starts without it. Two Custom Variables steps can both define status; {{ 3.status }} and {{ 7.status }} remain separate values.
Use a workspace variable when the same maintained setting must be available to many workflows or future runs. Use Custom Variables when the value is produced or decided during this run.
File: a reusable workspace asset
Use Files for content whose identity as a file matters: a document template, reference text, configuration file, image, spreadsheet, or data set.
Select the file from a step’s file picker where one is available. A reference can also use its file id:
{{ $file.<id> }}Text files, JSON, XML, and YAML insert up to the first 512 KiB of their contents. Other files usually insert a short-lived download link, so do not treat the resolved value as a permanent file URL. Test with the same kind of file you will use in the Live workflow.
Use a workspace variable for a short setting such as Europe/Prague; use a file when the content is naturally maintained, uploaded, downloaded, or forwarded as an asset.
Literal field value: configuration local to one place
Type a value directly when it is fixed, non-sensitive, and meaningful only to that field:
approved
30
https://api.example.com/v1/ordersA literal is often the clearest choice for an action name, a fixed status, a limit used once, or ordinary message text. It travels with the workflow and changes only when someone edits that field.
You can mix literals with mapped values:
Order {{ 2.ret.order_id }} is ready.Move a literal into a workspace variable when several workflows must change together. Move it into a secret when the value is sensitive. Keep it literal when centralizing it would make the workflow harder to understand without improving reuse.
Common decisions
| Situation | Best fit | Reason |
|---|---|---|
| A Gmail step sends from a team account | App connection | The step needs authorization to act in Gmail. |
An HTTP Request sends Authorization: Bearer … | Secret | The field needs sensitive token text. |
| Every workflow sends alerts to the same public channel name | Workspace variable | One visible setting can be updated centrally. |
| A run calculates whether a review is required | Custom Variables step | The flag exists only for that run. |
| Several AI steps use the same policy document | File | The document is a reusable asset, not a short setting. |
One step always writes the status processed | Literal field value | The value is local, fixed, and non-sensitive. |
Avoid look-alike storage choices
- A secret is not an app connection. It supplies text to a field; it does not create an account in an app step’s Account dropdown.
- A workspace variable is not a Custom Variables value. The first is shared across workflows and runs; the second is output from one numbered step during one run.
- A file is not a long variable. Store document-like content as a file so file-aware steps can select, forward, or download it correctly.
- A literal is not a safe place for a credential. Put sensitive values in secrets even when only one step currently uses them.
What’s Next?
- Connecting an App: Add an account and select it from an app step.
- Secrets and Variables: Create, reference, update, and rotate workspace values.
- File Management: Upload reusable assets and reference them from workflows.