Where an agent can act
Org reach decides whose records one of your agents may touch, when your app has organizations of its own.
If your product serves several customers, your app has organizations of its own: the companies or teams your users belong to, with their rows kept apart. Inside the app, each user sees only their own organization. You, as the app's owner, see all of them from the console.
An agent you create in the console acts for you without you clicking each step, so it does not inherit that view. It gets an org reach: an explicit statement of which of your app's organizations it may act in.
Two questions, two settings
An agent needs both of these before it can touch a record:
- Roles decide what it may do: list invoices, update an order, call an endpoint.
- Org reach decides whose records it may do that to.
Neither widens the other. A role that grants invoices:update does nothing in an organization
the agent cannot reach, and reaching every organization grants nothing a role does not.
The three settings
| Reach | Means |
|---|---|
| None | No organization's records. This is the default for every new agent. |
| All | Every organization in the app, including ones created later. |
| These organizations | Only the ones listed. A deleted organization drops out; a new one never joins until you add it. An empty list is the same as none. |
Whatever the setting, the agent always reaches records that belong to you, the app's owner: rows and items with no organization. So an app with no organizations of its own needs no reach at all.
Set it on the agent's page under Where it can act. Only you, as the app's owner, signed in to
the console, can change a reach; any other attempt is 403 ORG_REACH_OWNER_ONLY. A change applies
from the next thing the agent does.
Working across organizations
An agent that reaches more than one organization is told which organization each row belongs
to: rows carry an org_uid, and it can filter and group by it. Its tools take an optional
orgUid:
- Creating a row in a table whose rows belong to an organization must name one within reach,
or the call is refused with
400 ROW_ORG_REQUIRED. AnorgUidoutside its reach is400 ROW_ORG_NOT_FOUND, the same answer as one that does not exist. - Updating a row never moves it to another organization.
- Reading a record in an organization it cannot reach behaves as if the record were not there.
API keys narrow it further
An API key has an org reach of its own, and a call made with it acts within the overlap of the two: a key never reaches past its agent. The key's reach also starts at none, so a new key on an agent that reaches every organization still reaches only your own records until you set the key's reach too. Set it from App access › API keys, on the key's row, under Org reach.
That lets one agent serve several integrations, each held to the organizations it is for.
Agents that belong to an organization
Org reach is for your agents: the ones you create as the app's owner. An agent that belongs
to one of your app's organizations acts only in that organization, always, and a reach setting
does not apply to it (409 ORG_REACH_NOT_APPLICABLE). An agent whose organization the app no
longer recognizes acts in nothing and is refused with 403 AGENT_ORG_UNRESOLVED.
Your assistant has one too
Arbiter, the assistant in the console, also acts for you without you clicking each step, so it has its own reach in each app. Set it on the app's Agents page under Your assistant in this app. It starts at none, like everything else that acts for you.