Skip to main content

Working with credentials in flows

Some steps act on another system: they update a record in your CRM, close a ticket, or call an internal tool. Whoever performs that step, a person or an AI agent, needs access to that system. Your flow should say which access a step uses and why, but it should never contain the access itself. That is what a credential reference is for: it names a credential kept in the Secrets Vault and explains what the step needs it for. The Vault holds the value and decides which agents may open it.

Never put a secret in your content​

No password, API key, token or connection string belongs in a bit, a reference, an interactive element or a trail note, not even temporarily. Anything you type there can be read by everyone who can read the content, and it stays there after the real credential changes. Where a step needs access, add a credential reference instead.

If a secret was pasted into content by mistake, change it in the system it belongs to first, then replace the text with a credential reference. Deleting the text alone is not enough.

Put the reference in the step that uses it​

Add the credential reference to the bit whose step actually uses the access, not to an introductory bit or a reference document. A step that touches two systems gets two references. People and agents then see exactly which access each step involves, at the moment they need it. To review every credential a flow uses, look at the flow's Credentials view rather than listing them all in the first bit.

Always write a purpose​

When you insert a credential reference, fill in its Purpose: one line saying what the access is for in this step, for example "Read the customer's open invoices in the billing system." Describe the use, never the value or how to obtain it. The same credential can serve different purposes in different steps, so the purpose belongs to the step.

A reference without a purpose shows a "No purpose" warning in the editor. It still saves, but readers and agents will see that access is involved without knowing why.

Use the narrowest access, with an honest name​

Credentials are named by the people who store them in the Vault. Good names say which system and which level of access they give, such as a read-only and a write credential for the same CRM. When you choose a credential for a step, pick the narrowest one that does the job: a step that only reads should not reference a credential that can also write. Remember that the name is visible to everyone who can read the bit, so it should be descriptive but never sensitive.

If the credential a step needs does not exist yet, you can still reference it by name and ask an account admin to store it.

Inline or on its own line​

  • Within text puts a small pill inside a sentence. Use it when the access is a detail of the instruction: "Look up the account in the CRM using" followed by the pill.
  • New line puts a card on its own line. Use it when the step is mainly about that access, so the card explains itself.

You can switch between the two later from the reference's properties (Display: Inline or Card).

When a person does the step​

A credential reference tells a person which access a step involves; it never shows them the value. If people perform the step, say in the bit that they should use their own access to that system. The reference then informs them rather than blocking them, and the same flow still works when an agent takes the step over.

Quick checklist​

  • No secret anywhere in the flow's content.
  • Each credential reference sits in the step that uses it.
  • Each one has a purpose that explains the use.
  • Each step uses the narrowest access that does the job.
  • Steps that people perform tell them to use their own access.

Last reviewed: 2026-09-30