Skip to navigation

Secrets

View as Markdown

Secrets store credentials such as API keys, passwords, and bot tokens as encrypted values. They belong to your organization, so you can reuse one secret across multiple workflows. Workflow steps reference the secret’s name instead of storing the credential in their settings.

Save a secret

  1. Open Workflows and click Variables & secrets beside New workflow.
  2. Select the Secret Variables tab. You can also open Secret Variables directly.
  3. Click Create Secret.
  4. Enter a Name, such as crm_api_key, and paste the credential into Value.
  5. Click Create Secret to save it. The table shows its name, reference, creation time, and last rotation time.

Secret names must start with a lowercase letter, contain only lowercase letters and underscores, and be at most 64 characters long. Numbers, spaces, and hyphens are not supported. Use a unique name within your organization. Enter just the name, such as crm_api_key, rather than secret.crm_api_key.

Secret values are write-only. After saving, you can see the name and reference, but you cannot reveal or copy the saved value. To replace a credential, use Rotate.

Create or select a secret inside a node

Credential fields such as Bot Token in Slack nodes and API Key in JotForm Submit have a Select a secret dropdown.

  1. Open the node’s settings and open its secret dropdown.
  2. Select an existing secret, or choose Create secret….
  3. If creating one, fill in Name and Value, then click Create Secret. The new secret is saved and automatically selected for that field.

The new secret also becomes available in the other secret pickers in the builder. It is saved to your organization immediately, independently of publishing the workflow. Choose Manage secrets from the dropdown to open the Secret Variables page in a new browser tab while keeping the builder open.

NodeCredential to select
Slack Channel Message or Direct MessageA secret containing the Slack Bot User OAuth Token in Bot Token.
JotForm SubmitA secret containing the JotForm API key in API Key.
SFTP Upload, Download, or List DirectoryA password secret, a private-key secret, or both. At least one credential is required.

These fields require secret references. A plaintext credential or a public variable will not satisfy that requirement.

Use a secret in an expression

Fields that support expressions, including HTTP headers, can reference secrets too. Select the secret from the variable picker, or use its reference in an expression:

secret.crm_api_key

For an HTTP service that uses a bearer token:

  1. Save the token as crm_api_key using the steps above.

  2. Open an HTTP Request node.

  3. Under Headers, click Add and enter Authorization as the header name.

  4. Switch the header value’s mode to CEL only, click Edit expression, and enter:

    "Bearer " + secret.crm_api_key

Apply the expression in the editor to save it to the field. Use the authentication format required by the service you are calling. For a header that expects the API key alone, use secret.crm_api_key without the bearer prefix. See Call an API for the rest of the workflow.

Rotate a secret

Rotate a secret when you need to replace its stored credential while keeping the same name.

  1. Open Workflows > Variables & secrets > Secret Variables.
  2. Find the secret and click Rotate.
  3. Paste the replacement credential into Value.
  4. Click Rotate to save it.

Every workflow referencing that name uses the same secret, so a rotation affects all of them. Rotating in Gail updates the stored value; it does not generate or revoke a credential at the external service.

Runs already in progress keep the values they started with. New manually started, webhook, and debug runs use the updated secret once the change takes effect. Scheduled workflows keep the snapshot from their last publication, so republish scheduled workflows after rotating a secret they use.

Delete a secret or change its name

To delete a secret, click Delete on its row, then confirm with Delete in the dialog. Workflows that still reference it can fail when they next try to use it.

There is no rename action. To change a name, create a secret with the new name, update the fields that use it, test and publish the affected workflows, then delete the old secret. Because saved values cannot be read back, you will need to supply the credential again when creating the replacement.

Troubleshooting

What you seeWhat to do
A secret with this name already exists.Select the existing secret, rotate its value, or choose another name.
A secret is required for this field.Open the dropdown and select or create a secret.
This field must reference a secret.Replace the field’s existing value with a selection from the secret dropdown.
A secret created in another tab is missing from the builderLet your workflow changes save, then reload the builder to load the current secret list.
The Secret Variables page cannot loadClick Retry. If the error persists, contact support with the error message, without including the credential.
A scheduled workflow still uses an old credentialRepublish that workflow after rotating the secret.