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).
| Field | Example | Meaning |
|---|---|---|
| Name | smtp_password | How the secret is referred to in the diagram. Letters, digits, -, . and _. |
| Environment variable | SMTP_PASSWORD | The 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.
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.
WF_SMTP_PASSWORD=my-very-secret-password
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 diagram | Meaning |
|---|---|
secret.telegram = settings:telegram | The 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.
| Key | Setting |
|---|---|
telegram | Token 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​
- An administrator enters the token from @BotFather in System > Settings > Telegram API.
- In your diagram, place the event Telegram Chat and enter only the name of the bot.
- 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. - 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 run | What to do |
|---|---|
| Secret 'x' is not declared | Add 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 entered | An administrator enters the token in the system settings, Telegram API. |
| The environment variable 'WF_X' for secret 'x' is not set | Set the variable on the server and restart it. |