Skip to main content

Secrets

Workflows often need credentials: the password of a mail account, the token of a CRM, an API key. Such values must never be typed into a diagram, because diagrams are saved, copied, shown to the AI agent and may be stored in your Google Drive. A diagram therefore only names a secret; the value stays in the environment of the server.

Create a secret in three steps​

1. Declare it in the diagram​

Click on an empty spot of the canvas to show the properties of the diagram and unfold the section Secrets (the number in brackets tells how many secrets the diagram declares).

FieldExampleMeaning
Namesmtp_passwordHow the secret is referred to in the diagram. Letters, digits, -, . and _.
Environment variableSMTP_PASSWORDThe variable of the server that holds the value.

The field for the variable already shows the prefix WF_ in front. You do not have to type it, and you do not have to type capitals: smtp_password is stored as WF_SMTP_PASSWORD. Press + to add the secret.

There is no field for the value on purpose.

Why the prefix?

Only environment variables that start with WF_ can be used by a diagram. Otherwise a diagram could read the credentials of the application itself (for example its database password) just by naming them. The prefix can be changed by the administrator with the property workflow.secrets.env-prefix; the editor always shows the one in use.

2. Set the value on the server​

Set the environment variable where the server is started and restart it.

service.env (Docker setup, see Installation)
WF_SMTP_PASSWORD=my-very-secret-password
Started from a shell
export WF_SMTP_PASSWORD='my-very-secret-password'

After the restart, the row of the secret shows set. not set on the server means the variable is missing or empty; not allowed means the declared variable does not start with the prefix. Edit the variable of such a row and the prefix is added.

3. Use it in an activity​

Write the secret wherever an activity takes text, e.g. the password of an e-mail account or a header of a REST call:

${secret:smtp_password}

The value is looked up at the moment the activity needs it.

What happens to the value​

  • It is never stored in the diagram, in the variables of a run, in the task details, in the log or in the chat with the agent.
  • If it shows up in a text anyway (e.g. a server echoes it), it is replaced by ***. Values shorter than 6 characters are not masked, so use longer secrets.
  • In a dry run no value is read; *** is used instead.
  • Before the agent starts a real run of a diagram that uses secrets, you are asked, and the question lists the names of the secrets.
  • Files that an activity writes are not masked: do not write secrets into files.

Secrets from the system settings​

Some credentials are not kept in the environment of the server but entered once on the settings page by an administrator, for example the token of your Telegram bot (System > Settings > Telegram API). A diagram can use them as secrets as well, and again only the name is stored in the diagram:

Declaration in the diagramMeaning
secret.telegram = settings:telegramThe secret telegram is the bot token of the system settings.

Activities that need such a credential add the declaration themselves. When you place a Telegram event or Send Telegram Message activity in a diagram, in the editor or through the AI agent, the secret telegram shows up in the section Secrets with the note From the system settings: telegram and the state set or not entered in the system settings. Nothing has to be typed or pasted, and nobody has to know the token.

The value is read when the diagram runs, so a token that is changed on the settings page applies to the next message. Only the settings that are listed in the table below can be used, other settings (such as the API keys of the language models) cannot be named by a diagram.

KeySetting
telegramToken of the Telegram bot (System settings, Telegram API)

You can write the secret in your own texts as well, ${secret:telegram}, or without declaration as ${secret:settings.telegram}. If you want one diagram to use another bot, change the declaration of that diagram to an environment variable, secret.telegram = env:WF_SUPPORT_BOT; the activity uses whatever the diagram declares under the name telegram.

Example: a Telegram bot​

  1. An administrator enters the token from @BotFather in System > Settings > Telegram API.
  2. In your diagram, place the event Telegram Chat and enter only the name of the bot.
  3. Place Send Telegram Message after it. Open Secrets in the properties of the diagram: the row telegram (From the system settings: telegram, set) was added.
  4. Start the diagram. The bot receives its messages and the answers are sent with the same token, which never appears in the diagram, the variables of the run, the log or the chat with the agent.

If the row says not entered in the system settings, the administrator still has to enter the token; the run reports that in its log, without the value.

Secrets of your account​

Some settings of your account are available as secrets without a declaration, e.g. ${secret:user.push.privateKey}. See Secrets of the user.

Troubleshooting​

Message of the runWhat to do
Secret 'x' is not declaredAdd the secret in the section Secrets of the diagram.
... is not allowed: it must start with 'WF_'Edit the variable of the secret; the prefix is added.
The setting 'telegram' ... is not enteredAn administrator enters the token in the system settings, Telegram API.
The environment variable 'WF_X' for secret 'x' is not setSet the variable on the server and restart it.