Use in automations

Once credential is created in the environment, you use it in the playbook by name, using the credential(...) expression function. You never write the actual value.

credential() function

In any field that accepts an expression, type:

= credential("nombre-de-la-credencial")

Depending on the format of the credential, you use it in two ways:

Formato	How to read	Returns
Unique value	= credential("api-token").ToPlainText()	The secret as text
Varios campos	= credential("db")["password"]	The value of that field

// Credencial de valor único
= credential("openai").ToPlainText()

// Credencial con varios campos
= credential("db")["host"]
= credential("db")["user"]
= credential("db")["password"]
= credential("smtp")["password"]

Credential type parameters

Some activities (for example, connecting to a database or sending mail) have a credential parameter. = credential("nombre") is passed directly into these fields and the activity extracts the data it needs. In normal text fields (an API header, for example), use ["campo"] or .ToPlainText() to get the specific value.

How to solve it, step by step

1. On the playbook you write = credential("erp").
2. When executing, the agent detects that reference and asks Zoan Cloud for the value of the erp credential of the environment where it runs.
3. Zoan Cloud returns the encrypted value; the agent decrypts it in memory, only for that execution.
4. The activity uses the value. It is never written to the project file or logs (when printed, a credential appears as [credential]).

sequenceDiagram
  participant P as Playbook
  participant A as Agent
  participant N as Zoan Cloud
  P->>A: = credential("erp")
  A->>N: pide "erp" del entorno
  N-->>A: valor cifrado
  A->>A: descifra en memoria → usa → descarta

Requisitos

• The agent must be connected to Zoan Cloud. If you run a playbook using credential(...) without an active session with Zoan Cloud, it fails with a clear error asking you to connect. Therefore, credentialed playbooks are tested with Agent connected.
• The credential must exist in the environment where the execution runs. If it does not exist, the execution fails indicating which credential could not be resolved.

Common errors

Error	Causa	Solution
no hay proveedor de credenciales configurado	You ran without connection to Zoan Cloud	Connect the Agent to Zoan Cloud before running
La credencial 'x' no pudo resolverse	Does not exist in that environment, or the name does not match	Create it in the environment or correct the name
Parameter expects credential but received text	You passed a literal instead of the expression	Use = credential("nombre"), with = at the start

Good practices

• Consistent names between environments (erp, not erp-prod): the same playbook runs in production and testing without changes. See Environments.
• Rotate without touching the playbook: Change the value in the portal and the next run uses the new secret.
• Do not copy the value to a variable and print it: extract the secret as late as possible and only where it is needed.

Next steps

• Credential Management — create and manage credentials.
• Expressions — the syntax of credential() and other functions.