accountId on
every call, reads and writes alike, including when you can reach only one
account. A call that names its account neither reads nor changes the connection’s
stored selection, which stays only as a fallback for older calls until removal
(see below).
accountId required on every tool except get_status (optional there) and two
writes, named below. Its description is “Apostra accountId this call runs in, from get_status.”
Two writes list it as optional for now, because their accountId used to name
the thing being written: save_account (the child account to edit) and
save_directed_campaign_subscription (the account at the outside ad platform).
On those, send accountId beside the renamed input (id or
providerAccountId); an accountId sent without it is still read the old way
until the old shape is removed. A save_account call that creates an account
(it carries accountType) never carried the old meaning, so there accountId
is always the account the call runs in. Send it on every create, with
organizationId when the new account belongs to an Organization other than the
one the call runs in.
Get the account ID from get_status
Call get_status with no accountId. If you can act in several accounts, it
lists them in accounts, by name, with each account’s accountId and kind. If
you can act in one, it returns that account’s status. Call it with an
accountId to read that account’s identity, readiness, blockers and next
actions. A long list is paged: send the nextCursor it returns as cursor. See
Account access for the fields.
If you are not sure which account the person means, ask them. Do not guess
between accounts, and do not pick the first one on the list. Your agent should
remember the account the conversation settled on and send it on every later
call.
One conversation can work across accounts
Each call runs in the account it names, for that call only. Two calls in the same conversation can name different accounts, so you can read a Buyer Account and a Seller Account side by side by naming each one per call. A named call stores nothing and does not change the connection’s stored selection, so it never moves another conversation on the same connection. Two conversations can work in two different accounts at the same time.Naming an account never grants access
accountId says which account you mean. The server still decides whether you
may act there, using the same checks as before: your membership in the account
or an administrator role on its parent organization, the permissions on your
role, and the limits of your credential. A credential fixed to one account
(WorkOS user and organization API keys, machine credentials, buyer agents and
API keys with no user behind them) can name only that account, and
get_status lists no other it can name. A buyer agent reaches an account its
organization’s grants cover by naming that account’s advertiser in
advertiserId, never by accountId; get_status lists those accounts with
nameWith: "advertiserId".
An Apostra staff member who is a member of the account, or an administrator of
its organization, acts there with that role, the same as in the web app. One
who names an account they are not a member of gets the platform support access
that applies to that account and nothing more.
Errors
ACCOUNT_NOT_REACHABLE repeats the number you sent and looks up nothing from
it. Take the accountId from get_status, not from the error.
What still works while this rolls out
Tool lists are cached by hosts until a person reconnects, so many conversations still run on a list from beforeaccountId was required. Until a removal date,
those conversations keep working:
- A call that omits
accountIdstill runs, in the account your connection last switched to, or in your credential’s home account if it never switched. Its result carries one line telling you to sendaccountIdon every call. A write from a connection that can be switched still fails withACCOUNT_CONFIRMATION_REQUIRED. expectedAccountIdis no longer listed, becauseaccountIdreplaces it. The server still accepts it. SendaccountIdinstead.switch_accountis retired and no longer appears in any tool list. A client working from a cached list can still call it. The result says it is retired and tells you to sendaccountIdon every call instead.
switch_account and expectedAccountId
are removed. Do not build on the fallback.
The V3 HTTP API
A V3 HTTP request names its account the same way:accountId in the JSON
body of a tool call, or the accountId query parameter when reading a write
receipt or a document. The server checks it exactly as it checks the account a credential
may use, and naming an account never grants access. A credential bound to one
account may leave accountId out.
The X-SCOPE3-CUSTOMER-ID header is deprecated. It still works until the
removal date, and a request that names its account only by the header gets a
Deprecation: true response header and a Link to this page. If a request
sends both and they differ, it fails with ACCOUNT_MISMATCH and nothing is
read or written. After the removal date a request that sends the header is
refused. See HTTP API.
Inputs that were called accountId
Five inputs used accountId for a different account. They have new names, so
accountId always means the account the call runs in.
During the rollout, an older call that leaves out the new input keeps the old
meaning of
accountId on the first four, except a save_account create. open_media_partners_page has no such
fallback: its accountId always names the account the call runs in. See
v3 Concepts for how
the server tells the two shapes apart.
Related
- Account access covers which account a call runs in when you name none, organization accounts and account kinds.
- Errors covers the full V3 error envelope.
- Quickstart shows the first
get_statusread.