# Secrets (/platform/credentials)





Secrets store API keys, tokens, passwords, and other values by name. Reference a saved value with `{{KEY}}` instead of placing a literal secret in a workflow field. Saved secret values are encrypted before storage.

## Scope and access [#scope-and-access]

Open **Settings → Secrets** in your workspace. The editor has **Workspace** and **Personal** sections.

| Scope | Storage and management | Runtime access |
| - | - | - |
| **Workspace** | Stored for this workspace; workspace Admins and that secret's Credential Admins can manage and reveal it | Workspace Admins and members with an active Credential Member or Admin grant can use it |
| **Personal** | Stored once for its owner across their workspaces; the editor manages your own values | Resolves under the authorized personal identity and current credential grants |

Workspace members, including external collaborators, can see workspace secret names. Seeing a name or having Write workspace access does not automatically grant use or reveal access. Creating a workspace secret requires **Write** or **Admin**. Managing an existing one requires Admin authority on the secret or workspace.

Personal secrets belong to their owner. Workspace and organization Admin roles do not grant access to them. Existing explicit personal credential grants can participate in runtime resolution, but the current Secrets editor and membership API do not create new personal-secret shares.

Credential Members can reveal a workspace secret only when its Admin enables [Show value in logs and Chat](#visibility). See [Roles and permissions](/platform/permissions#credential-access) for credential grants.

## Add, import, edit, or delete a secret [#add-import-edit-or-delete-a-secret]

1. In the last empty row of the appropriate section, enter a **Key** such as `OPENAI_API_KEY` and its **Value**.
2. Use only letters, numbers, and underscores in the key. A new empty row appears as you type; saved values are masked by default.
3. Select **Save** to persist the changes.

To import several values, paste `.env` content into a key or value field. The parser supports `KEY=VALUE`, `export KEY=VALUE`, quoted values, and inline comments.

Edit cells directly. To delete a secret, select its row's trash icon and save. Update workflow references before deleting it: blocks that require the deleted value cannot resolve it.

## Use a secret [#use-a-secret]

Type `{{` in an input to open the variable picker. Available secrets are grouped by scope. Selecting one inserts a reference such as `{{OPENAI_API_KEY}}`; Sim resolves it to the real authorized value at runtime.

Among secrets the execution actor may use, the **workspace value takes precedence** over a personal value with the same name. An inaccessible workspace secret does not shadow an authorized personal value.

### Resolution identity [#resolution-identity]

Workspace secrets authorize against the execution actor: an identifiable caller, or the workspace's configured billing account for background execution. The run sees only the workspace secrets that identity may use.

The personal namespace depends on the trigger:

| Run started by | Personal namespace |
| - | - |
| Clicking **Run** or using a personal API key | The person running it |
| A workspace API key, schedule, webhook, or deployed chat | The workflow owner |
| An unauthenticated public API URL | None |

The workflow-owner fallback supports background workflows authored against that owner's keys; it is not a grant to borrow any person's secrets. An owner who has left the workspace or is suspended cannot supply that personal namespace. A stale workspace execution identity can also lose its secret access.

Use workspace secrets with appropriate grants for production and public deployments. If an owner leaves, blocks requiring their personal values may fail even though workspace-backed blocks can continue. A public API caller receives no personal namespace.

## Secret details [#secret-details]

Select **Details** on a row to open its detail page. You can inspect the key and, when authorized, reveal or edit the value. Return to **Secrets** or save changes from the detail page.

Workspace secrets also have:

* **Description** for an optional purpose or rotation note.
* **Members** and **Share** to grant teammates Credential **Member** or **Admin** access.
* **Visibility** to control **Show value in logs and Chat**.

Description, member-sharing, and visibility controls do not apply to personal secrets.

### Visibility [#visibility]

By default, Sim protects recognized secret values in log-facing and model-bound content. **Show value in logs and Chat** opts one workspace secret out of that protection. With it enabled:

* Run logs, Chat, and code output can show its real value instead of `{{KEY}}`.
* Files written with the value can remain readable and attachable.
* The Secrets API list can include its value when the caller has the required access.
* Credential Members can reveal it under **Settings → Secrets**, without gaining edit permission.

<Callout type="warn">
  The value can become visible to anyone who can see the workspace's runs, including public shared-log links and exports, regardless of the secret's member restrictions. Enable this only for values safe to print, such as a non-sensitive base URL.
</Callout>

Only a workspace or Credential Admin can change this workspace-only setting. It affects future runs: already masked logs stay masked, and previously written plaintext remains even after protection is restored. If another protected secret has the same value, protection wins.

### See usage [#see-usage]

Select **See usage** to open its **Logs** and **References** views:

* **Logs** lists runs that resolved the secret: source workflow, Sim agent or MCP server; trigger; resolution identity; last use; and a link to the most recent run. Rows are grouped by day, so repeated scheduled runs can share one row.
* **References** shows saved workflow fields, custom tools, and MCP configuration that name the secret. A saved reference can exist before anything has run; it is different from recorded use.

Only Admins of a workspace secret, or the owner of a personal secret, can inspect its usage. Other members see a disabled action because the trail identifies workflows, people, and run IDs. Two owners with the same personal key name see their own records independently.

Usage is recorded separately from execution logs, so log expiry does not delete the usage record. It records recognized resolution, subject to the limits below. An empty trail means no use was recognized; it does not prove the secret was never used. Check both usage and references before rotating or deleting a key.

## Execution log protection [#execution-log-protection]

After a saved secret is successfully substituted through `{{KEY}}`, Sim masks exact, case-sensitive occurrences of its resolved value in log-facing content, unless it is exempt under **Show value in logs and Chat**. The replacement is normally `{{KEY}}`.

Protected content includes:

* The editor's live block logs and Logs **Overview** workflow input and output.
* Stored execution traces, log-read API responses, and the Logs block's **Get Run Details** output.
* Function and Agent span inputs, outputs, and errors.
* Agent thinking and tool-call arguments, results, and errors.

Blocks, tools, and downstream steps still receive the real runtime value. Sim protects a separate copy for logs; it does not rewrite stored functional execution data, execution responses, streams, callbacks, block state, or snapshots. A workflow that returns a secret can therefore put it in its functional response even when the corresponding Logs view is masked.

Model requests receive a separate protected projection. Exact recognized secret values are replaced before model-visible messages, prompts, tool arguments, or tool continuations leave Sim. This follows the same visibility exception and exact-value limitations; it does not remove secrets from the runtime operations that need them.

### Direct environment reads in workflow code [#direct-environment-reads-in-workflow-code]

Sim also activates protection when it recognizes a direct secret read in workflow code before execution:

| Language | Recognized forms |
| - | - |
| JavaScript | `environmentVariables['KEY']`, `environmentVariables.KEY`, `const { KEY } = environmentVariables` |
| Python | `environmentVariables['KEY']`, `environmentVariables.get('KEY')` |
| Shell | `$KEY`, `${KEY}` |

The scanner reads code rather than executing it. It can report a named key even if code shadows the environment binding with its own object, overwrites a variable before reading it, or assigns to the name rather than reading it. **See usage** can therefore include a secret that the run had available but did not read.

Assigning to the injected environment object does not change the stored secret. The object is built for the run and discarded afterward. Edit stored values under **Settings → Secrets**.

The scanner does not recognize a secret read when:

* Its name is built at runtime, as in `environmentVariables[keyName]`, `${!indirect}`, or `$@`.
* `eval`, `printenv`, or a sourced file hides which key is read.
* The code reads another object, such as `other.environmentVariables['KEY']`.
* It cannot distinguish executable expansion from text. A shell `$KEY` inside single quotes or a quoted heredoc such as `<<'EOF'` does not expand.

An unrecognized read does not activate masking or appear under **See usage**. A hardcoded literal by itself does not activate secret protection.

### Protection limits [#protection-limits]

<Callout type="warn">
  Masking and model projection match exact values. Encoded, URL-encoded, hashed, transformed, fragmented, or piece-by-piece values are outside that protection. Do not deliberately return, print, or transmit a secret to an unintended destination. Protection is a safety net, not a boundary for arbitrary code.
</Callout>

## Secrets in Chat code execution [#secrets-in-chat-code-execution]

Sim's Function and code-execution tools in Chat mount a saved secret only when their code explicitly includes a valid `{{KEY}}` reference. Direct `environmentVariables.KEY` reads, shell `$KEY`, dynamic names, hardcoded literals, and configured-but-unused secrets do not mount values through this path.

Code execution requires workspace **Write** access. The execution actor must be allowed to use every requested secret: their personal namespace and active credential grants, or workspace Admin access to workspace secrets. Pending, revoked, or absent grants do not mount a value. This is use authority, separate from the authority to reveal a value in Settings or inspect its usage.

Code receives the real authorized value. Before a tool result returns to Sim, exact occurrences of activated protected values are replaced with `{{KEY}}`. Local side effects and functional runtime results are unchanged. Protection does not prevent code from sending a real value over the network; the same transformation and transmission limits apply.

### Headless secret selection [#headless-secret-selection]

The **Sim Chat** block exposes **Secret access** under **Show additional fields**. Inbox exposes it under **Settings → Inbox → Secrets**. Choose **All secrets** or **Selected secrets**.

Existing configurations default to **All secrets** for compatibility. This means explicitly referenced secrets that the execution actor may use; it does not inject the full environment. **Selected secrets** narrows that set. A reference outside the selected set rejects the code request rather than running it with a partial environment.

Inbox messages from allowed external senders do not receive raw-secret access. If Sim cannot match the sender to a workspace member, it runs without a secret actor, so `{{KEY}}` cannot resolve through this path. Allowing an email sender is not a credential grant.

Recurring work uses deployed workflow [Schedule triggers](/workflows/triggers/schedule). Configure secret access on the blocks that execute it; see [Chat actions and configuration](/chat/tasks) for the current setup flow.

## Related docs [#related-docs]

* [Roles and permissions](/platform/permissions)
* [Workflow variables](/workflows/variables)
* [Logs](/logs-debugging/logging)