Where Data Lives

Put each value where its lifetime, sensitivity, and purpose fit. App connections authorize a service, workspace assets are shared across automations, Custom Variables belong to one run, and literal values belong to one field.

This guide covers storage scope and lifetime, not geographic data residency. For required data regions and contractual retention or deletion terms, use the Security & Compliance review.

Choose the right home

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. Do not copy an account’s OAuth token into a secret or a field. Use a secret only when a field asks for a raw token rather than a Connection dropdown.

Secret: sensitive text used by a field

Store an API key, bearer token, webhook signing key, or password as a secret when a field must send the value itself:

{{ $secret.BILLING_API_KEY }}

A secret’s value is encrypted at rest and hidden in the Variables table. Admins and Managers have audited 10-second Reveal value and Rotate value controls. The API key type provides the same encrypted storage with a {{ $key.BILLING_API_KEY }} reference. Automations resolve references to plaintext at runtime. Never paste credentials as literals or place secret references inside AI prompts or logs. See Secrets and Variables.

Workspace variable: a shared, non-sensitive setting

Use a workspace variable for a shared setting that several automations read by name, such as a region or tax rate:

{{ $var.REGION }}
{{ $var.TAX_RATE }}

Variables are editable in place and resolved when each step runs (with up to a 10-second cache after an edit). Use a secret instead if exposing the value would grant access. Use a literal if only one field needs the value.

Custom Variables: values scoped to one run

The Custom Variables step creates named fields for later steps in the same run, such as an intermediate calculation or flag. If step 3 defines requires_approval, downstream steps read:

{{ 3.requires_approval }}

A Custom Variables value belongs to the numbered Step that created it ({{ 3.status }} and {{ 7.status }} remain separate). The next run starts without it, while its output stays in retained execution history until that history expires.

File: a reusable workspace asset

Use Files for a document template, configuration file, image, spreadsheet, or data set. Select the file from a step’s file picker or reference its 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. Files created by automations can have automatic deletion dates under Files → Created by workflows. Keep a separate copy if you need longer retention.

Literal field value: configuration local to one place

Type a value directly when it is fixed, non-sensitive, and meaningful only to that field:

Order {{ 2.ret.order_id }} is ready.

Move a literal into a workspace variable when several automations must change together. Move it into a secret when the value is sensitive.

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 automations.