Connections

What it is. Everything your workflows and agents need to call external services: API keys, OAuth credentials, and brokered integrations.

Use it when your workflow calls any API, sends email, posts to Slack, or reads from a service that needs credentials. That is most workflows.

Swirls gives you three levels, in increasing order of how much it manages for you. Each level is a different primitive — not three names for the same thing:

1. Secrets — you hold the value. Declare variable names in the file, set values in the vault, and nodes read exactly the keys they declared.
2. Credential profiles — you describe the shape. Declare an auth block that wires secret vars into OAuth client credentials, API keys, basic, or bearer; the runtime applies it on outbound HTTP (or gates a public form when type: basic).
3. Connections — Swirls brokers OAuth. Declare a provider slot in the file, a human authorizes it once in the Portal, and short-lived tokens are issued at run time. No credentials exist in the file or the vault. Typed provider operations come as action blocks, browsable in the integration catalog and installable with swirls add. Providers we don't broker yet are a request away.

Prefer the highest level the target service supports. A connection beats a credential profile because there is no key to leak or rotate; a profile beats hand-built headers because the runtime applies it consistently.

On HTTP nodes, set auth: (your profile) or connection: (brokered OAuth), never both. Integration nodes and channels take connection: only.

These blocks are about your system reaching out. For controlling who can reach in to your agents and workflows, see Access.