credentialBindings.
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.
What a node stores
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.
The four choices
org_unit — a named company
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.system — Gloo's own Credential
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.fromInput — the company comes from a run input
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.An empty connections map — no Connection bound
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:
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 owncredentialBindings 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/oauth2in 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:pinnedwhen it comes from a procedure version’s manifest,livewhen 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:usefor it. Gloo’s own system Credential is offered when you holdcredentials:useat 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.
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:usefor 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:useat 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:usefor the agents the version runs.
What a refusal says
publisher_not_entitled
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.credential_binding_unbounded
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.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. 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 withget_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:readat one company cannot download a file that also carries another company’s data.
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.
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 asystem 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’scredentialBindings 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. 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), or send a Personal key 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).
List the draft nodes that carry a binding. consoleOnlyConfig names the Console-only fields set on a node, never their values:
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:
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:
Related
- Access — Delegation — who may act for which company.
- Vendors — the Vendor and Connection registry, and the OAuth Credential bindings.
- Compose a workflow — the surrounding authoring model.
- Trust Fabric — gates, holds, and the enforcement pipeline.

