Skip to content
Back to

Workspace secrets

A workspace secret is a named value, such as an API token or a password, that belongs to one workspace. Workflow nodes in that workspace use the secret by its name; the value lives in HashiCorp Vault and the workflow engine reads it only when a run executes the node. This page covers where you manage secrets, who can change them, and how REST API and Data Connector nodes use them.

Manage secrets

Section titled “Manage secrets”

Open the workspace’s … menu in the Workspaces explorer, or the … menu in the workspace header, and choose Secrets. Flow opens the workspace Config tab with the Secrets section expanded. Each Config section is collapsible and starts collapsed when you open the tab yourself.

The Secrets section lists every secret in the workspace with the time it was last set and who set it.

  • Add secret opens a dialog for a name and a value. Names start with a letter and use letters, digits, _, . and -, up to 100 characters, for example CRM_API_TOKEN. A value can be any length, up to 65,536 bytes.
  • Replace saves a new value under the same name.
  • Delete removes the secret. Nodes that use it fail on their next run until a secret with that name is added again.

Who can see and change secrets

Section titled “Who can see and change secrets”
Access to the workspace What you can do
Viewer See the secret names, when each was last set, and by whom
Editor or admin Add, replace, and delete secrets, and pick secrets in node settings

Your workspace access comes from the workspace Permissions and your role. See Roles and RBAC.

Every add, replace, and delete is recorded in the Activity log with the workspace, the secret name, and who made the change. The value is never part of the activity.

Use a secret in a node

Section titled “Use a secret in a node”

A node stores a reference to a secret, written {{secret.NAME}}, in place of the value. The workflow file, its history, and every run file hold the reference only. A field that can hold a secret shows Choose secret and Create secret inside it. Choose secret lists the workspace’s secrets by name; Create secret saves a name and value and selects it in one step. The chosen secret appears in the field as a padlock badge with its name, never its value; remove the badge to type a plain value or choose another secret. Fields for passwords, tokens, API keys, and client secrets accept only a secret.

Secrets are available in workflows that live in a workspace.

REST API node
Section titled “REST API node”
Field How it takes a secret
Authentication: bearer token, password, API key, client secret Always a secret
Authentication: username, client ID A plain value or a secret
Header values (Manual mode) Plain text, or a secret chosen inside the value field
Query parameter values (Manual mode) Plain text, or a secret chosen inside the value field
Header and query parameter bindings (OpenAPI mode) Choose the Secret binding
Authorization, Proxy-Authorization, and Cookie headers Always a secret

A secret is always the whole value of its field. The URL path and the request body take plain text only.

When a run executes the node, the workflow engine replaces each reference with the secret’s value. If a credential field or a credential header holds a plain value instead of a reference, the node fails and names the field. Session cookies and access tokens the node obtains with form login or OAuth2 are handled like secret values. See REST API node.

Data Connector node
Section titled “Data Connector node”

Fields the connector marks as secret, including the OAuth client secret, accept only a secret. When you choose Connect on a connector that signs in with OAuth, Flow asks for a Connection name, prefilled with the connector name. The tokens the provider returns are saved as workspace secrets named <connection name>_<field>, and the node references them.

  • Use the same connection name on several nodes to share one connected account.
  • Use a new connection name to keep accounts apart.
  • If the workspace already holds secrets with those names, Flow asks you to confirm before replacing them.

Agents and secrets

Section titled “Agents and secrets”

An agent that builds or repairs a workflow can check which secrets the workspace holds and ask you to set a missing one. The value goes only from you to the workspace.

  • Check: the agent sees what the Secrets section shows: each name, whether it is set, when it was last set, and by whom. It never sees a value or its length. The agent checks with your access, so it sees a workspace’s secrets only when you can.
  • Ask: the agent shows an amber padlock badge in the chat, Set NAME secret. Choosing it opens the Set secret dialog with the agent’s reason. Saving stores the value in the workspace, the same as Add secret, and needs editor or admin access.
  • Answer: the agent gets back only the secret name and whether you set it. Closing the dialog, or replying in the chat instead, tells the agent you did not set it.

For a connector that signs in with OAuth, the agent asks you to choose Connect on the node. When the chat runs in Slack or Microsoft Teams, you receive a link to the thread in Flow and set the secret there.

When a run executes

Section titled “When a run executes”

The workflow engine resolves every secret a workflow references from that workflow’s own workspace, at the start of each run. Secrets from another workspace, a team, or a person are never used.

  • Missing secret: the node that needs it fails with Secret NAME is not set in this workspace. Frozen and disabled nodes keep their last state and never fail for a missing secret.
  • Replaced value: the next run executes every node that uses the secret instead of reusing its previous output, so the new value takes effect. Replacing a value does not start a run by itself.
  • Error messages: secret values are removed from node errors and logs before you see them.

Copy and delete a workspace

Section titled “Copy and delete a workspace”

When you copy a workspace, the copy receives no secrets. Its workflows keep their references, and the nodes that use them fail with the missing secret’s name until a member of the copy adds secrets with those names.

When you delete a workspace, its secrets are deleted with it.

Backup

Section titled “Backup”

Secret values are part of the nightly backup in both backup modes, in the export of your secret store, and a restore writes them back. A fontana export of your install carries them in a separate file that only its owner can read. See Backup and restore.

Section titled “Related documentation”