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")["value"]	The secret as text
Varios campos	credential("db")["password"]	The value of that field

// Credencial de valor único
credential("openai")["value"]

// 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 ["value"] for a single-value credential) to get the specific value. .ToPlainText() is not allowed in expressions: the engine rejects it so the secret does not end up in arbitrary text.

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, based on the process’s folder (see below).
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

Which credential each robot uses

If you use folders, each robot uses its area’s credentials without changing the playbook. For a process in the Purchasing folder, credential("sap-prod") is looked up in this order:

1. In the process’s folder (Purchasing).
2. In the folders linked to it (see Link from another folder) and at the environment root.
3. If the environment has none with that name, in the organization’s global credentials.

• The folder is taken from the process on every run: if you move the process to another folder, the next run uses the new folder’s credentials.
• A process in a subfolder uses its own folder, what’s linked to it and the root; to use a credential from the parent folder, link it to the subfolder.
• If the environment has that credential in a folder the robot can’t reach, the run fails with a clear error instead of using the global one with the same name.

The same rule applies to integrations used by robots, by assistants (based on the assistant’s folder) and by extraction projects (based on the project’s folder). Flow steps use the environment root’s credentials and integrations and the global ones.

Requirements

• 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 and be within reach of the process’s folder. Otherwise, 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
La credencial «x» no existe o no está disponible desde la carpeta «y»	The credential is in another folder, or was unlinked or moved	Create it in that folder, link it to it, or keep it at the environment root
Parameter expects credential but received text	You passed a literal instead of the expression	Write credential("nombre") without quotes around it: it is an expression, not text

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.