# Where Data Lives

> Choose the right home for an app account, secret, shared setting, run-scoped value, file, or literal field value.

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. }}`         |
| 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](#secret-sensitive-text-used-by-a-field) 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.

```text
{{ $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.

```text
{{ $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:

```text
{{ 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:

```text
{{ $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:

```text
approved
30
https://api.example.com/v1/orders
```

A 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:

```text
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](/manage/apps-and-integrations/connecting-an-app)**: Add an account and select it from an app step.
- **[Secrets and Variables](/manage/workspace-settings/secrets-and-variables)**: Create, reference, update, and rotate workspace values.
- **[File Management](/manage/workspace-settings/file-management)**: Upload reusable assets and reference them from workflows.