> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bind node credentials

> Choose whose Credential each Connection a workflow node opens uses: the credentialBindings map, the wildcard key, the four scope choices, and the publish-time check.

This page is about the **node-level Credential binding**: the statement on a workflow node that says *which Connection this node opens, and whose Credential it uses*. It is stored on the node as `credentialBindings`.

> [!WARNING]
>
> The glossary entry [**Credential Binding**](https://docs.gloo.com/forge/concepts/glossary.md#credential-binding) names a different object: the OAuth connected-account binding, which grants one Forge scope access to one connected account and is administered under [Platform → Vendors](https://docs.gloo.com/forge/console/platform/vendors). That object is the stored Credential itself. The object on this page is a workflow-graph statement *about* which Credential to reach for. Same two words, two different things.

## Vendor, Connection, Credential — and Scope

Four words, one meaning each:

* **Vendor** — the third-party company Forge calls out to (QuickBooks, Planful, Slack).
* **Connection** — one addressable API surface of that vendor, identified as `vendorKey/connectionName`.
* **Credential** — the stored secret that opens a Connection.
* **Scope** — the **where**: the org unit a Credential belongs to. Scope is first-class; a Credential is stored under its Connection *and* a scope.

A Credential binding pairs a Connection with the scope whose Credential that Connection should use.

## What a node stores

```json theme={null}
{
  "version": 1,
  "connections": {
    "quickbooks/accounting": { "kind": "org_unit", "scopeId": "orgunit_0808821f", "scopeCode": "CP_MIDWESTERN" },
    "sage_intacct/xml": { "kind": "org_unit", "scopeId": "orgunit_1461269a", "scopeCode": "CP_EAST" },
    "sage_intacct/oauth2": { "kind": "org_unit", "scopeId": "orgunit_2550378d", "scopeCode": "CP_WEST" }
  }
}
```

`connections` is keyed by the Connection target (`vendorKey/connectionName`). The reserved key `"*"` means **every Connection this node opens** — it is the fallback the resolver uses when the map does not name the Connection exactly.

The example is one procedure node with three targets bound to three different companies. Each
target resolves only the Credential at its own exact scope. The three Credentials still enter one
sandbox, under their separate Connection namespaces.

Selection is two steps: the exact Connection key if the map has one, otherwise the `"*"` entry. A Connection matched by neither is **refused** — see [How a bound Connection resolves](#how-a-bound-connection-resolves).

## The four choices

> [accordion] org\_unit — a named company
>
> `{ "kind": "org_unit", "scopeId": "…", "scopeCode": "…" }`. The Connection uses the Credential stored at exactly that org unit. A Credential at a parent org unit is not reached, even one shared with descendants: bind the node to the org unit that holds the Credential. `scopeCode` is carried alongside the id so the binding survives a reseed that changes ids.

> [accordion] system — Gloo's own Credential
>
> `{ "kind": "system" }`. The Connection uses Gloo's own Credential, which is stored at the **system** scope, rather than a company's — and only that one: an agent's or a person's own Credential for the same Connection is never read first. This binding asks for no on-behalf-of grant at run time.

> [accordion] fromInput — the company comes from a run input
>
> `{ "kind": "fromInput", "inputName": "companyCode", "allowedScopeIds": ["…"] }`. Whoever starts the run names the company through that input. `allowedScopeIds` lists the org units the input is permitted to name; a newly published version is refused if the list is absent or empty (see below). Publishing takes `credentials:use` for **every** company on that list, because any of them can be the one the run names.

> [accordion] An empty connections map — no Connection bound
>
> `{ "version": 1, "connections": {} }` binds no Connection, exactly like a node with no binding: every Connection the node opens is refused. An empty map at the node level also overrides the workflow-level default, so it is how a node opts out of one.

## How a bound Connection resolves

Resolution is an **exact read** of the scope the binding names:

| Binding for the Connection | What is read |
| - | - |
| `org_unit` or `fromInput` | The Credential at exactly that one org unit, after the on-behalf-of grant check. No parent org unit, no system scope. |
| `system` | The Credential at the system scope, and nothing else. |
| none (no exact key and no `"*"`) | Nothing. The Connection is refused with `BINDING_ABSENT_FOR_CONNECTION`. |

A **procedure node** fails with `BINDING_ABSENT_FOR_CONNECTION` before its sandbox starts. An **agent node** still runs, but the tool whose Connection is unbound is refused: it resolves no Credential and the node's binding errors record `BINDING_ABSENT_FOR_CONNECTION` for that tool. A procedure node may bind its Connections to different companies, or mix company and `system` scopes in one sandbox. Before dispatch, Forge resolves the complete ordered target-to-scope vector and signs its digest into the procedure session grant. Each Credential consumer must present that same complete vector and may read only the chain paired with its target.

Forge also records the ordered vector on the step before dispatch. A retry reuses each target's recorded company even if a `fromInput` code or name now resolves differently. Every company in the vector is added to the run's company list; all step results and output files inherit that list, so reading an output from the three-company example requires the normal read permission at all three companies. A `system` target adds no company.

A procedure node's Connections and an agent node's tool calls do not fall back to the executing agent's or person's Credential, or to the system scope. The model an agent node uses for inference is not a Connection binding and is not affected; neither is a chat or factory agent, which reads the company its channel or task acts for, or its own chain when it acts for none.

## Node binding and workflow default

A binding can be set on a single node, or as a **workflow-level default** that applies to the nodes that do not carry one. The node's own `credentialBindings` wins where it is present; the workflow default applies otherwise. Because an empty map is itself a statement, a node can use one to opt out of the default.

The workflow default is stored as `defaultCredentialBindings`, using the same
`{ "version": 1, "connections": { … } }` map as a node. Authoring and reads accept
these maps; the former single `beneficiaryBinding` and `defaultBeneficiaryBinding`
forms are retired. Clearing a workflow default removes it; writing an empty node
map keeps that node from inheriting the default.

Both levels are set from the node and workflow panels in the workflow builder / Architect, and both are authoring: writing either takes the `workflows:write` permission. Setting the **workflow-level default** additionally takes `credentials:use` for every company its map names, decided by the same code the publish refusal runs, so a default you may not use is refused where you write it rather than surfacing later. Writing a **node-level** binding is not gated that way — a draft may name a company you are not entitled to, and the publish is where that is refused.

## What the picker offers

The builder does not type a scope id. The panel asks the server for the options, and the answer has two halves that are deliberately gated differently:

* **Which Connections this node opens** — not filtered by entitlement. You have to be able to see that a node needs `intuit/oauth2` in order to ask for the right role; what a node does is not a secret. Each Connection carries where the requirement came from and how stable that answer is: `pinned` when it comes from a procedure version's manifest, `live` when it comes from an agent's granted tools, where a later tool-grant change can widen it. A source that does not resolve — a missing procedure version, an agent that does not resolve, a node naming more tools than the read's bound — is reported as a gap, so a Connection the read could not see never renders as "nothing needed".
* **Which companies you may bind them to** — each company in the list carries whether you hold `credentials:use` for it. Gloo's own system Credential is offered when you hold `credentials:use` at the platform scope. When your role grants cannot be read — the resolver scanned past its grant limit, or your sign-in does not resolve to a user record — every company comes back unentitled with the reason, rather than as "you hold nothing". The company list is capped; when the cap bites, the response says so, so a short list never reads as the complete set of companies.

> [!NOTE]
>
> The picker is a convenience, not a control. Hiding an option does not enforce anything: the server decides again when the workflow-level default is written, and publish is the decision of record.

## Publish is where entitlement is decided

Publishing a version freezes which companies' Credentials that version may use, so the publisher's own authority is checked once, when the version is published, rather than on every run. The check reads the graph's nodes plus the workflow-level default and asks for:

* **`credentials:use` for every company scope the bindings name.** A binding that names an org unit takes that permission for the company, resolved against that scope and the scopes covering it — its ancestors, and the platform scope.
* **`credentials:use` at the platform scope for a `{"kind":"system"}` binding.** Gloo's own Credential is stored at the system scope; the permission to use it is read at the platform scope.
* **`agents:use` for the agents the version runs.**

A publish that fails this is **refused**, with one issue per missing item. It is a refusal, not a request held for approval.

### What a refusal says

> [accordion] publisher\_not\_entitled
>
> One issue per missing item. A Credential issue (`credentials_use_missing`) names the company and the Connections that bound it: *"Publishing binds company CP\_MIDWESTERN to "quickbooks/accounting", which takes the Credential user role for that company. Ask someone who holds it to publish, or have it granted to you."* A `"*"` binding is described as *every Connection it resolves*. An agent issue (`agents_use_missing`) names the agent.

> [accordion] credential\_binding\_unbounded
>
> A `fromInput` binding carries no `allowedScopeIds`: *"Credential binding on Connection "…" takes its company from run input "…" without saying which companies that input may name. List the allowed companies on the binding, then publish."* This is decided before any authority lookup — it is a wiring statement to complete, not a permission to obtain.

> [accordion] publisher\_authority\_unreadable
>
> The role-grant resolver scanned past its limit and returned nothing rather than an arbitrary subset. This is a defect to report, not a statement about what you hold.

> [!NOTE]
>
> A version that binds no company, uses no system Credential, and runs no agent asks for no authority, and publishes as it did before this check existed.

## At run time

A binding that names a company (`org_unit` or `fromInput`) also needs authority to act for that company. A published run needs an **on-behalf-of grant** on its own workflow version, which publish writes when the publisher is entitled. A draft test run needs its launching person to hold `credentials:use` at that company. That grant is a separate, enumerable record, administered at [Trust Fabric → Access → Delegation](https://docs.gloo.com/forge/console/trust-fabric/access#delegation). Without a covering grant, the dispatch fails with `No active on-behalf-of grant authorizes …` rather than falling back to another Credential. The workflow gate refuses it before the node runs, with the code `OBO_NOT_GRANTED`; it is not held for approval, because approving never creates a grant.

## Outputs carry the companies they came from

A run keeps a list of the companies (org units) whose data its outputs may contain: every company a Connection's Credential resolved to, plus the companies already on anything the run read — an input file, a file read with `get_file`, another run's results, or a sub-workflow's output. A `system`-scoped Credential adds no company, and the list only ever grows. Every step result the run writes and every output file it produces carries the run's list.

Reading those outputs then needs the surface's usual permission where the run lives **and** at every company on the list:

* A single run, step, checkpoint, trace or file you may not read for one of its companies is refused with that surface's usual permission error. The error does not name the company.
* A list (runs, steps by agent, run artifacts, outcome and search results) leaves such rows out; a page can come back shorter than asked.
* A platform-scope grant covers every company. An API key or external application is checked through its own role grants, so a key granted `files:read` at one company cannot download a file that also carries another company's data.

A run that used only `system` Credentials carries no list and reads exactly as before. Runs recorded before this rule were stamped by the deploy-time checkpoint `output-companies-backfill-v1`.

Chat sessions and agent memory follow the same rule. A chat session keeps its own list: the company its agent acts for, plus the companies on any memory it recalls, any file it reads, and any run posted back into it. Every agent, tool and system message in the session carries the session's list; your own messages carry none. Memory an agent writes carries the list of the session or run it came from.

* In a transcript, a message you may not read for one of its companies keeps its place but shows as withheld, and the agent's replies and live output in that session are withheld the same way (`chat:read`). Your own messages are never withheld.
* Memory lists, the memory export and the memory API leave out a memory you may not read (`memory:read`); fetching one by id is refused.

Knowledge carries its list in a later release.

## Checking where the bound Credentials sit

A bound node reads a Credential only at exactly the scope its binding names. Each of these is a Connection the run refuses: a Credential that sits only at an ancestor org unit that shared it down, a Credential only at the system scope, a node with no binding at all, and a `system` binding with no system-scope Credential. The fix is to move or copy the Credential to the bound scope, or to bind the node to the scope that holds the Credential. Forge reads where a Credential sits, never what it holds: secrets are write-only.

A draft does not run in production; only a person's draft test run executes it. A binding on a draft node starts to matter when you publish the draft, because the published workflow's active version is what runs.

## Do it over the API

Setting a node's `credentialBindings` is done in the builder's picker: it is a Console-only field, and a draft-node write over HTTP that names it answers `400`. Over the API you can confirm which draft nodes carry a binding and publish, which is where entitlement is decided. These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). The quickstart's `ACCESS_TOKEN` does not carry every scope they need, so mint it again with `scope=workflows:read workflows:manage agents:use credentials:use` from an app whose roles hold them (see [Requesting scopes at token mint](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint)), or send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-scopes) whose scopes include them; `workflows:manage` is elevated, so tick **Include elevated permissions** when you choose the key's scopes (see [Approve and administer scopes](https://docs.gloo.com/forge/console/settings/personal-keys.md#approve-and-administer-scopes)).

List the draft nodes that carry a binding. `consoleOnlyConfig` names the Console-only fields set on a node, never their values:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/draft-graph" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data.nodes[] | select(.consoleOnlyConfig | index("credentialBindings")) | {nodeId, name, type}'
```

This needs `workflows:read` at the workflow's home.

Publish the draft. `expectedActiveVersionId` is the version you expect to be active now, or `null` if none has been published:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/publish-draft" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bound-workflow-publish-v1" \
  -d '{"expectedActiveVersionId": null, "publishNote": "Bind the accounting Connection"}' \
  | jq '{data, error}'
```

Publishing needs `workflows:manage` at the platform scope, and the credential's scopes must also include `workflows:read`. Publish checks `credentials:use` at each bound company and `agents:use` for the agents the version runs, as a Console publish does; a key or External App also needs both among its own scopes beside `workflows:manage`, or a draft that binds a company or runs an agent is refused. A refusal is `422` whose message begins with the gate's code, such as `publisher_not_entitled`, and nothing is written. A different active version than the one you name answers `409`.

Over MCP, `forge_call_read_operation` reads the same draft graph. It is in the default `start` job:

```json theme={null}
{ "operationId": "getWorkflowDraftGraph", "input": { "id": "<workflow id>" } }
```

## Related

* [Access — Delegation](https://docs.gloo.com/forge/console/trust-fabric/access#delegation) — who may act for which company.
* [Vendors](https://docs.gloo.com/forge/console/platform/vendors) — the Vendor and Connection registry, and the OAuth Credential bindings.
* [Compose a workflow](https://docs.gloo.com/forge/build/compose-a-workflow.md) — the surrounding authoring model.
* [Trust Fabric](https://docs.gloo.com/forge/run/trust-fabric.md) — gates, holds, and the enforcement pipeline.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.