/mcp/v3) is listed the same complete
tool catalog, whatever kind of account you are in and whatever role you hold.
Apostra’s in-product assistant keeps its account-scoped tool list for now. The account a call names
decides whether it can run. Begin every new session by calling get_status with
no accountId. When you can reach more than one account it lists them, with
each account’s accountId, kind and name, so you can ask the person which one
they mean. When you reach one account it returns that account’s status directly.
Keep the returned account identity, readiness and blockers for the account you
work in.
Then name that account on every call with an accountId returned by
get_status:
switch_account is retired on V3: it is not in
any tool list, and it still runs for now from tool lists that hosts cached
earlier.
Which account a call runs in when you name none
SendaccountId and this section does not apply. Until the removal date
announced in Name the account on every call, a call from
a cached tool list that names none still runs in the account the server picks,
in this order:
- The account the connection last switched to, if it has a stored selection and you still reach that account. A stored selection belongs to the connection (the sign-in grant) or, when there is no grant, to the person. Some clients, such as ChatGPT, carry no session, so they read the stored selection on every call. A client that keeps a session, such as Claude, starts a new session on your home account and ignores a selection stored by an earlier one. Naming an account on a call never changes it.
- Otherwise your home account. For an Apostra staff member it is their staff account. For everyone else it is the oldest active membership; a legacy Seller membership that is not yet set up is skipped when you have another account.
accountId on every call. A buyer agent, and an API key
with no user behind it, can name only the account it runs in, so
get_status lists no other account it can name, even when a hosted buyer
agent is answering a person who belongs to other accounts. A buyer agent whose
organization granted it advertisers in other accounts sees each of those
accounts in reachableAccounts with nameWith: "advertiserId", up to 10 of
its advertiserIds, advertiserCount, and access (read when every grant
there is read-only, otherwise read_write). A call that names one of those
advertisers in advertiserId runs in that account, and naming the account in
accountId is refused.
When you can reach more than one account and name none, get_status lists
them. The structured result carries accounts, and the text lists the same
accounts after a paragraph that says the account was chosen by default.
nextActions leads with confirm_account, a recommended step that names the
account the call ran in and where it came from. You can answer a read-only
question in that account. Tell the person which account you used. Confirm the
account with them before your first write, then send that accountId on every
call. get_status with accountId reads another account.
A page lists up to 25 other accounts. An Apostra staff member reaches every
customer, so their list is paged: the text says how many accounts are not shown,
and
nextActions carries a list_more_accounts step with the cursor to send.
Send cursor only on a call that has no account named; with an account named,
or with one account reachable, there is no list to page and the call is refused.
A call that names its account, a caller with one account and a credential fixed
to one account see none of this.
Every authenticated Buyer, Seller and Organization account can connect, and
every connection to /mcp/v3 is listed the same complete catalog: Buyer, Seller,
Organization and Agents tools, search and get with all their kinds,
filters and includes, and every write tool, even for a read-only login or a
directory reviewer’s login. Listing a tool is not permission to run it:
- A tool runs only in an account of its kind. A call in the wrong kind of
account is refused with
WRONG_ACCOUNT, naming the kinds the tool needs and the accounts you can reach that can run it. Send one of them asaccountIdand call again. The same goes for the includes that read a Seller account’s own state:get({ kind: "seller" })withidentity,readiness,operating,entitlements,teachingorprebidis refused withWRONG_ACCOUNToutside a Seller account, naming the include. Asked for with anid, they are refused withVALIDATION_ERROR, because another seller’s own state is never readable. - A call needs the role it always needed. Without it, the call is refused with
ACCESS_DENIED. A directory reviewer’s login is refused every write withREVIEWER_TOOL_PROHIBITED.
get with kind: "advertiser_access" is seller-only by design and shows the
seller who may buy for an advertiser; for buyer-side access questions, see
organisation delegation.
Manage organization accounts
A direct organization administrator manages the organization’s child accounts withsave_account, from the organization account or any child account they
administer. Send no id to create a child, id and name to rename one, or
id and isArchived to archive (true) or restore (false) it. Each of
those is recorded for approval on the website: the tool returns a link, nothing
changes until an administrator of that organization approves the exact request,
and the agent cannot approve it.
Repeat the same call with the same idempotencyKey to see the outcome. Send
dryRun: true first to see what the request would do, including the campaigns
and media buys that block an archive. A preview runs the same checks and
records nothing. See Manage accounts with a V3 agent
for the fields each change takes.
The in-app Apostra chat also offers save_account to a direct organization
administrator using an administered Agents, Buyer, or Seller account. The
chat returns the same website approval link, and no account changes until an
administrator approves that exact request there. Direct organization
administration that takes effect immediately stays available only from a direct
session.
An Apostra support person with an active staff elevation on the organization
(see “When Apostra staff help with your account’s members” below) can list
the organization’s accounts and request the same creates, renames, archives
and restores from the organization account, under their own name. An
elevation on one child account does not reach the organization. While the
elevation lasts they can also approve those requests on the website. If the
elevation has ended or been revoked by the time an approved change runs, the
change is refused and nothing is changed.
An organization has no limit on how many Buyer or Seller accounts it holds, so
restoring one is never refused for a count, and archiving or restoring an
account changes nothing about what else you can add. Restoring or reactivating
an account is never refused because of the plan either: an account the
organization held keeps its place even if its plan no longer allows that type
for a new one. Creating accounts is
capped at 25 in any 24 hours per organization. The 26th is refused with
429 RATE_LIMITED, details.reason account_creation_daily_limit and a
message to contact support to raise the limit; do not retry it, because the
window slides over 24 hours. It counts creations, so an account you created and
then archived or deleted still counts, while restoring one does not, and
repeating a request with the same idempotencyKey is never refused. A
save_account create, including its dryRun preview, is refused with the same
error when you ask, so no approval is recorded.
See Accounts in an organization.
Two other checks remain. The
plan must allow the account type you create; otherwise the request is refused
with 409 CONFLICT, details.reason plan_does_not_cover_account, the plan that
would allow it and the next step. The same check refuses a staff create, moving
an account into the organization, and switching an account to Storefront.
And an organization holds one Agents
account: creating or restoring a second is refused with 409 CONFLICT and
details.resource developer_account_limit, so build further agents in the
existing one. Repeating a request with the same idempotencyKey returns the
first result.
Account types
save_account creates an account of one type. Send accountType and, for a
seller, sellingMode:
The Agents account is the account type where you build and manage agents. Its
wire value is still
developer.
A seller needs sellingMode; a buyer, an Agents account and a Demo Storefront refuse
it with VALIDATION_ERROR. operatingMode (LISTING_ONLY or
AGENTIC_MEDIA_COMPANY) still works as the older name for the same choice, and
sending it with sellingMode is refused. It will be removed once the hosts that
list save_account have approved the new definition.
Which of these an organization can add depends on its plan. The Listing plan
allows Listing accounts and one Agents account; adding a Campaign management or a
Storefront is refused, and the next step is to move to the Standard plan.
Read the answer for your organization from the organization account’s
get_status instead of trying a create. Its organization.addableAccountTypes
lists the four types above, each with canAdd. A type you cannot add also has a
reason (code and message) and a nextStep (code, message, and canAct,
which is false when only another administrator of the organization can take the
step). A save_account create or dryRun for a type that canAdd says no to is
refused with that same reason, because both come from one plan check. If the read
fails, addableAccountTypes is null and gaps says so.
The organization account’s get_status shows the child account counts and which
account types the organization can add (see Account types); an
organization has no limit on how many accounts it holds. It
also says whether the organization has an Agents account. If none exists, its
next step is to create one with save_account; an organization holds one
Agents account, and a second is refused. get with kind: "account" and
include: ["lifecycle", "capacity"] adds one child’s archive state and
blockers. These reads and the writes check that you
are a direct administrator of that organization. Send organizationId to
save_account to act for an organization from a child account you administer;
without it the call acts in the organization account you are connected to. A
Apostra platform operator can name any customer organization, and only an
operator can create a Demo Storefront (accountType: "seller" with
demoStorefront: true).
An organization administrator can make these calls from any of their own
signed-in sessions: their home account, a child account they switched to,
customer view, Murph or an MCP OAuth connection. The server checks their direct
administrator membership of the named organization; access inherited from a
parent organization is not enough. An Apostra staff member in a support session
gains nothing from support access: they can act on an organization only through
their own direct administrator membership of it. An API key, a machine
credential, a delegated agent and a session
acting as another person are refused with ACCESS_DENIED, even when the person
behind them administers the organization. A platform operator who is not a
member of the organization must call from their own home account: one working
in a customer account is refused, so send your home account’s accountId, then
retry.
Browsing products under your company’s seller account is open to every
member of the company and to the company’s service tokens, not only to
administrators; buying still needs an Operator or Admin or a token that
is not read-only. See
who can browse under a company seller account.
Who decides an account’s approvals
A creative review or a media-buy approval on a Seller account goes to that account’s approval audience. With no saved approval routing, the audience is the account’s own administrators. If the account has none, it is the administrators of the organization the account belongs to. Only the audience is notified about it. An administrator of the organization may also decide any approval that is routed to administrators (the default routing, or saved routing that names the Admin role), even when the account has administrators of its own. They are not notified about it; they decide it from the account’s approvals or withsave_work_item. An approval whose saved routing names particular people, and
no role, can be decided only by those people.
Spend approval on a buyer account
Each buyer account has a spend approval setting,requireSpendApproval. When
it is on, no new money reaches a seller until an administrator of the account
approves it on the Apostra site, whoever asks: an agent, an API key, Murph or a
person in chat. It is off unless an administrator turns it on.
What waits for approval while it is on:
- Launching a campaign. Confirming a launch that would book media buys with sellers, including a media buy staged on a campaign that is already live. See Confirm launch.
- Adding a product to a live media buy.
- Raising what a live media buy spends: a higher total budget, or a higher sum of its line item budgets. See Change a live media buy.
- Applying optimizer suggestions that raise a live media buy’s spend. Even in automatic mode, the suggestion set waits for a decision and then an administrator’s approval. Sets that only lower budgets or bids apply as usual.
approval_required with the
approval’s id, its link on the Apostra site and when it expires, recorded under
the call’s idempotencyKey. Nothing was sent to a seller. Show the person the
link, then repeat the same call with the same idempotencyKey to see the
outcome (Approving agent requests). A v2 buyer
route returns HTTP 409 with code SPEND_APPROVAL_REQUIRED and the same
approval in details.approval.
Who approves: an administrator of the buyer account, or of the organization
it belongs to, signed in to the Apostra site in their own browser. The
approval runs the request exactly as it was recorded. If what the campaign or
media buy would spend changed after the request, the approval fails and nothing
is sent, and the agent asks again. An approval expires after 24 hours.
- Read it on
get_statusin a buyer account (account.requireSpendApproval, always present), and on account rows fromsearchandget(kind: "account"), where it istrueorfalseon a buyer account andnullon any other account. - Turn it on with
save_account, sendingid(the buyer account) andrequireSpendApproval: true. It saves at once and returnssaved, orunchangedif it is already on. Areasonis optional and is kept in the account’s audit log.dryRun: truechecks it first and saves nothing. - Turn it off with
save_account, sendingid,requireSpendApproval: false, areasonand anidempotencyKey, and nothing else. Turning it off is itself recorded for an administrator’s approval on the Apostra site, so an agent cannot remove the check it works behind. It returnsapproval_requiredwith the link.dryRun: truechecks it first. On an account where it is already off, the call returnsunchangedand records nothing. - Who can change it: an administrator of the buyer account, or of the
organization it belongs to. Each account has its own setting; there is no
organization-wide switch. Service tokens, impersonated sessions and Apostra
support sessions cannot change it. A seller, organization or Agents account
has no setting, and naming one returns
VALIDATION_ERROR.
When a Seller account can’t sign in yet
A Seller account can be used once it has been set up as an Apostra Seller. When an administrator of the account signs in with a work email on the company’s own domain (the domain recorded on the account), sign-in finishes that setup and lets them in, the same way signing up as a new Seller does. You’ll be asked to accept the current Terms of Service if you haven’t yet. Anyone else, for example a member who is not an administrator or who signs in with an email on another domain, can’t sign in until the account is set up. The sign-in page says the Seller account isn’t set up yet, and our team is told which account it is. You don’t need to request access or fill in the Buyer access form. Ask your company’s administrator to sign in, or sign out and sign in again once the account is ready. Sign-in refuses such an account withALPHA_OPT_IN_REQUIRED and
reason: "seller_awaiting_setup". A Buyer account that is not yet in the
advertiser beta gets the same error with reason: "buyer_not_enrolled", and
can request access. The signed-in account read (/auth/me) reports the same
value as accessRefusal, or null when the account is not refused.
What signup creates
Signing up for Buyer or Seller access creates a new organization with your first account inside it, and makes you the organization’s administrator. The account is the one you chose at signup: a Buyer account for Campaign management, or a Seller Account. It keeps its own id. The Terms you accepted and the plan you took sit with the organization, so you can add more accounts withsave_account
(see Manage organization accounts)
without converting anything first. A colleague you invite to the organization
joins the organization; a colleague you invite to the account joins only that
account. Invite colleagues to the organization when they should reach every
account in it. A new Seller Account still starts as a Listing account.
Some signups do not create an organization. Joining a company that already has an
account, by invitation, by claiming an account nobody administers, or by an access
request, adds you to that account (see below). Agents signups already
create an organization. Accounts that signed up before this change, and accounts
Apostra staff create, can still be standalone; see
Turn a standalone account into an organization.
If the organization cannot be set up, signup does not finish and says so. Signing
up again finishes it.
Requesting access to your company’s account
When you sign up with a work email and your company already has an account, signup offers Request Access instead of making a second account. This includes the Agents experience: if a colleague already created your company’s Agents account, you ask its organization’s administrators for access, and you are told so before you reach the Terms. The account’s administrators are emailed your request, and you get access when one of them approves it. If the account has no administrator, and neither does the organization above it, nobody there can approve the request. It comes to our account team instead. We email you when you have access, or if we need anything from you. If you have questions in the meantime, write to support@apostra.com. An email address on the account’s domain does not by itself make you that account’s first administrator. Verifying your mailbox proves the address is yours, not that the domain is your company’s, and many domains are shared by people from different companies — university alumni addresses, mail forwarders and some internet providers among them. We make you the first administrator without review only when the organization has proved it controls the domain, either by publishing the DNS record we ask for or through a check by our account team. Until then the request goes to the account team, as above. Asking again does not file a second request; your first one stays in place.Who an account’s member list shows
search with kind: "member" lists the people with access to an account, and
get with kind: "member" reads one of them by the id search returned. In
an organization account you can name a direct child account: filter.accountId
on search, memberAccountId on get. In any other account you read the
account you are working in. Reading the list takes the authority to manage the
account’s members: an administrator of the account or of its organization. See
Name the account on every call.
Every member says where their access comes from in accessSource:
searchreturns both kinds, ordered by email. It has no filter onaccessSourceand itsquerymatches only the id, email and name. To see only the organization’s administrators, readaccessSourceon the rows, and raiselimitwhentruncatedistrue.getfinds an organization administrator by id on a child account.- A person who is both added to the account and an administrator of its
organization is listed once, as
direct, with the level they hold on the account. - An organization account has no organization above it, so every member of it
is
direct. - Apostra staff who reach an account through a support session, a staff elevation or an account switch hold no membership of it and are not listed. A staff member who administers the organization is listed like anyone else.
- The member read is read-only. To remove an
organizationmember, or change their access, use the organization’s Members page, not the account. - Removing a person’s administrator membership of an organization removes their
organizationaccess to every account in it, deactivated accounts included. A person who was also added to an account directly keeps that membership until it is removed on the account itself.
When Apostra staff help with your account’s members
An Apostra support person who opens your account sees it read-only. To change anything they need a staff elevation for your account, which is approved inside Apostra, lasts a limited time and is recorded. While it lasts, they can list the account’s members, invite someone, resend or cancel an invitation, change a member’s role and remove a member, the same as an administrator of the account. An elevation on an organization covers the members of the accounts under it. Every change is recorded under the staff member’s own name. Once the elevation ends or is revoked, these actions are refused again.When your account has been deactivated
An account can be deactivated, for example when it is closed or merged into another account. No one who belongs to it can use it until it is restored. If every account you belong to has been deactivated, signing in does not stop at an error. You are shown any invitation you have to another account first; if there is none, you are taken to signup to set up a new account, and you administer the account you create there. The deactivated account is left as it is: if it is restored later, you can use it again. If you belong to more than one account, deactivation only matters when none of them is active; an active account still signs you in. If you would rather get the deactivated account back, ask its administrator to restore it, or email support@apostra.com. When signup is not offered, sign-in answers a deactivated account with403,
error: "NO_ACTIVE_HOME_CUSTOMER" and reason: "ACCOUNT_DEACTIVATED", with a
plain-language message that agents and API clients can show as it is. That
happens on token refresh, and on password sign-in when the email address has
not been verified. Browser sign-in with OAuth, SSO or a verified password sends
the person to signup instead. A sign-in that asks for one particular account,
such as a link into a specific seller’s advertiser, is answered about that
account: when it is deactivated the sign-in is refused, and the person is not
sent to signup, because they asked for that account and not for a new one.
Before your organization accepts the Terms of Service
Until a direct administrator of your organization accepts the current Terms of Service, the Apostra site asks for that before anything else. Only that administrator can accept them; Apostra staff never accept them for you. Managing the account’s members is not blocked. If you are an administrator of the account or its organization, the Terms window offers Manage members, so you can invite or remind the person who should accept. An Apostra support person with an active staff elevation on your account gets the same choice. The member list, invitations and role changes work as usual; most other work waits for the Terms. Conversion events keep flowing.log_event and the conversion endpoint
POST /api/v2/buyer/advertisers/{advertiserId}/log-event accept events
whether or not the current Terms are accepted, so an integration that sends
your conversions never loses data while you sort out the Terms.
Sandbox advertisers and live spend
A sandbox advertiser is an advertiser created with AdCP’s ownsandbox
flag set to true. You set it once, in save_advertiser when the advertiser
is created, and it is carried on the AdCP account identity
{brand, operator, sandbox}. It cannot be changed afterwards: save_advertiser
on an existing advertiser that names sandbox returns IMMUTABLE_FIELD. To
move to live work, create a new advertiser without the flag.
A sandbox advertiser only sees products from sellers with a usable sandbox
setup for that advertiser. For an Apostra-managed Google Ad Manager seller,
that means a bound advertiser or the seller’s ready sandbox advertiser. If the
seller has neither, use a live advertiser to see its products.
Every brief a sandbox advertiser sends carries the same flag on its account,
and a seller on Apostra is not charged for answering it. Sandbox briefs are
also left out of the seller’s analytics (its run counts, win rate, buyer asks
and top products), and out of what the seller’s Storefront Agent learns from
past briefs, so a buyer’s tests do not look like demand to the seller. What the
seller teaches the agent on a sandbox brief, such as a lesson, still applies to
live briefs.
An Apostra Storefront still answers a sandbox brief in full, so you test the answer a live brief
would get. A seller’s own sales agent may answer sandbox requests differently.
Because a sandbox brief is never charged, the seller needs no plan and no
payment method to answer one. It does need active Brief Acceptance rules on the
Storefront that handles the brief, so the seller’s own rules decide what it
answers, test briefs included. Brief Acceptance the seller has turned off still
meets this: turning rules off is a decision, not missing setup (see
Turn a policy off). Where Apostra requires a seller to finish setting
up before it answers briefs, a sandbox brief is refused only for missing Brief
Acceptance rules (details.reason seller_prerequisites_missing, with
details.missing naming brief_acceptance_rules). It is never refused where a
live brief to the same seller would be answered.
A live advertiser’s brief is also free to the seller while its buyer account
cannot book media yet, for example because the account has not finished setup.
These briefs come from a real advertiser,
so unlike sandbox briefs they stay in the seller’s analytics and in what its
Storefront Agent learns. Once the account can book, its live briefs are
charged as usual. A brief sent to a seller’s agent with no Apostra buyer
account behind it is always charged, and if Apostra cannot check the account’s
setup in time, the brief is charged as an ordinary live brief.
Each buyer account has 20 sandbox briefs a day that reach an Apostra
Storefront, counted in UTC. While the account cannot book media yet, its free
live briefs count toward the same 20. One brief sent to many sellers in a single
request_proposals call counts once; a direct get_products call to an Apostra
Storefront with a sandbox account counts as one brief, and so does a refine pass
on one. A catalog read (get_products with buying_mode: "wholesale") is not a
brief and never counts. A brief Apostra answers
from its recent results, such as the same brief sent again shortly after, does
not reach the Storefront and does not count. A brief that reaches the Storefront
counts even if the Storefront then cannot answer it. Live briefs from an
account that can book have no such limit.
Sandbox briefs to Apostra’s synthetic sellers, the Apostra synthetic seller and
every Demo Storefront, never count, so you can build and test an agent against
them as often as you need. A request_proposals round from a sandbox
advertiser whose sellers are all synthetic is never refused for the limit. A
round that also names a real seller, or one sent to every eligible seller,
still is.
Past the limit, the limit is Apostra’s, not a seller’s, and the answer says so.
A request_proposals call from a sandbox advertiser that has used its 20 briefs
is refused once, before any seller is contacted, with RATE_LIMITED. This
applies to every new round from that advertiser until the reset, including a
round whose sellers are not Apostra Storefronts, except a round sent only to
synthetic sellers. The message names the limit and says it resets at midnight UTC, and retry_after
is the number of seconds until then. A direct get_products brief or refine
call to an Apostra Storefront gets the same RATE_LIMITED and retry_after; a
catalog read is still answered. If another round uses
the last brief while yours is running, an Apostra Storefront that refuses it
reports the same Apostra limit as that seller’s outcome, not as a seller error.
If Apostra cannot read today’s count, request_proposals is refused with
SERVICE_UNAVAILABLE and a short retry_after, and no brief is sent.
An account that cannot book media yet reaches the same limit with its live
briefs. The up-front request_proposals refusal, and the refusal a direct
get_products call gets, have details.reason
not_transacting_brief_daily_limit and list what the account still needs in
details.blockers, such as operator_identity. A seller outcome inside a
running round says only that the Apostra limit was reached. The limit lifts
as soon as the account can book, as well as at midnight UTC. If Apostra cannot read
today’s count for such a brief, the brief is sent and charged as an ordinary
live brief rather than refused.
A buyer account has no sandbox mode and no live mode. The account is the same
in both cases; what changes is which checks an operation has to pass.
Setting up a sandbox advertiser (creating, updating or archiving it, and
configuring its tracking) does not wait for the verified operator identity, so
you can prepare one before claiming it. Creating its campaigns and media buys
does.
An operation that fails a check is refused with an access-denied error that
names the first requirement still missing. See
Sandbox mode for the full list of requirements and the
buyer REST behavior.
Your application should retain the account identity with every workflow
checkpoint, send it as
accountId on every call, and verify it when resuming. A connection, a seller relationship,
or a registered agent does not implicitly grant access to every advertiser.
Full account-access reference
Review customer relationships, role and permission behavior, and stable v2
account switching in the canonical account-access guide. That guide’s
customer_switch is v2 only.