- Agent: the software actor you recognize by name and purpose.
- Installation: that agent’s presence in your organization.
- Principal: the durable internal identity Apostra uses for routing and audit. Its
principalId(for exampleprin_yq8Kd...) is the only identifier of the principal. Most people need it only when troubleshooting. - Credential: how the software proves its identity. Secrets are shown once and never displayed again.
- Connection: a configured way for the agent to connect to Apostra, exchange data, or use an organization-owned reporting resource.
- Grant: explicit permission to act for an advertiser. An installation, principal, credential or connection is not a grant.
buying kind,
so the account’s status lists it with its stage, as it lists a sales or creative agent.
The record only tracks the agent. The principal stays the credential, and the agent’s
authority stays as advertiser grants on the Buyer account.
An agent runs in one of two ways under the same model. An external agent is software
you run yourself and connect through the flows below. A hosted agent is software
Apostra runs for you; see Hosted buyer agents.
Who can manage buyer agents
Only a person signed in directly as an administrator of the organization can list, read or change the organization’s buyer agents from a Buyer or Developer account. A support session, an impersonated or simulated session, a delegated session, an API key and an OAuth client are all refused, reads included, withACCESS_DENIED. The one
exception is a buyer agent reading its own record with id: "self". The organization
always comes from who you are signed in as. A call cannot name a different organization,
so it can never reach another organization’s principals. Agents a person claimed into one
of your accounts follow the account’s own rule; see
Agents claimed into an account.
Identity is not authority. Holding a principal or a credential gives no advertiser,
account, spend, payment or Terms access. That comes from separate per-advertiser grants
and is never implied by identity.
A principal has a kind and a lifecycle state:
- A buyer agent is one automation your organization runs. It holds credentials, and you administer those credentials.
- An organization operator is your organization acting as itself. Apostra creates it the first time an organization credential calls. It is not a buyer agent and has no credentials to administer.
- The lifecycle state is
active,suspendedorretired. A buyer agent is suspended when it has no active credential left, and every call it makes is then refused until you add one. ItsprincipalIdis kept for audit and never reissued.
Read your agents
Usesearch with kind: "buyer_agent" to list the organization’s buyer agents. It takes
a query and a limit, and returns total and whether the list was truncated. Use
get with kind: "buyer_agent" and the agent’s principalId as id for one agent. An
agent can read itself with id: "self".
Each agent has these fields:
A read returns no issuer URLs, WorkOS organization IDs, client IDs, domains,
brand.json or JWKS URLs, signing key IDs or key fingerprints. Those are credential
facts, not identity.
Create, rename and change an agent
save_buyer_agent states the end state you want, and the fields you send decide the
change. With no id it creates an agent. With an id it makes exactly one change:
A call that sends fields from more than one change, or an
id with none, is rejected
with VALIDATION_ERROR.
To create an external agent, send displayName:
id in a later call to set access or lifecycle.
Sending idempotencyKey with an external create is refused; it is only for
kind: "hosted".
Set advertiser access
access is a complete replacement of the agent’s grants, up to 500 advertisers, and it
must carry the expectedAccessRevision from your latest read. A stale revision is a
conflict. Read the agent again and re-apply the list you want, and never retry the same
body automatically.
Pause, resume or retire
Lifecycle changes are state-fenced. SendlifecycleState with expectedLifecycleState,
the state the agent must be in for the change to apply.
Agents claimed into an account
An agent can register itself with Apostra and then be claimed into one of your Buyer accounts by a person (see Claiming your agent). A claimed agent is a registered agent. It acts on the whole account it was claimed into, with no more than the role of the person who claimed it. It holds no advertiser grants and no credential you administer here.Who can see and revoke them
An administrator of the account the agent was claimed into can see and revoke it, directly or as an administrator of that account’s organization. They must be signed in as themselves: in the web app, through OAuth, or with their own API key. An agent’s own credential is refused, so an agent cannot revoke itself or another agent. Support, impersonated and simulated sessions are refused too. In the web app, an administrator sees and revokes them under Settings → API keys → Manage buyer agents, in the Claimed agents list. Each agent shows the client it named, when it was claimed, and whether it is active or revoked, with when and by whom. Revoke asks you to retype the agent’s name and says revocation is permanent. The page shows what the API answers, including a refusal, and decides nothing about who may revoke. The list holds at most 10 agents and says when more exist. In Claude, ChatGPT and Murph,open_buyer_agents_page opens the same list as a Page in a Buyer account,
with the same Revoke confirmation. It reads with search and revokes with save_buyer_agent, so it shows
what those calls answer, a refusal included.
Read them
search with kind: "buyer_agent" lists the agents claimed into the account the call is
made in, after your organization’s buyer agents. The list holds at most 10 agents in all,
organization buyer agents first, so a query of agent_reg_ narrows it to claimed agents
and truncated says when more matched than were returned. get reads one by its id. A registered
agent has these fields:
credentials and access.advertisers are always empty for a registered agent, because its
authority is the account, not advertiser grants.
Revoke one
Sendsave_buyer_agent with the agent’s id, lifecycleState: "retired",
expectedLifecycleState: "active" and its display name as confirmationText:
403 and "error": "AGENT_REGISTRATION_REVOKED", and Apostra also
revokes the registration with its identity provider. Revocation is permanent and cannot
be undone. What the agent already did in the account stays. To use an agent in the
account again, register a new one and have a person claim it.
Revoking an agent that is already revoked succeeds and changes nothing, so a retry after a
lost reply is safe. Revoking is the only change a registered agent takes: a rename, an
access change, a credential handoff or a pause is refused.
Apostra can also revoke a claimed agent, for example one that misbehaves. When it does, it
emails the account’s administrators to say which agent and why, and revokedBy reads
{ "kind": "apostra_staff" }.
What a grant allows
- A grant names advertisers your organization owns, in your account or in another
account of your organization. A buyer agent never reaches more than your organization’s
own users can. A grant on an advertiser another organization owns is refused with
ACCESS_DENIEDanddetails.reason: "ADVERTISER_OUTSIDE_ORGANIZATION", even when that organization shared the advertiser with yours through an advertiser grant. A grant of that kind saved earlier gives the agent nothing: the advertiser is left out of its access list and every request for it or its campaigns is refused. An archived advertiser is left out the same way. READlets the agent read an advertiser’s campaigns, creatives, media buys and reporting. On V3 the read tools areget,search,get_status,get_deliveryand theopen_*tools. Every other tool, including eachsave_*andrequest_*tool, is a write. A write under aREADgrant is refused withagent_read_only.READ_WRITEallows writes as well.- A call names its advertiser. On V3 it names it with
advertiserId,filter.advertiserIdonsearch, orfilters.advertiserIdonget_delivery, andgetof an advertiser names it byid. A call that names none but addresses an existing campaign or media buy by id runs for the advertiser that owns it, when that campaign or media buy belongs to your organization. Asearchof an advertiser-owned kind such as catalogs or creatives that names no advertiser uses the agent’s only granted advertiser, or lists its granted advertisers to choose from. Otherwise a call uses the connection’s selected advertiser. An agent with grants on more than one advertiser has none selected, so such a call is refused withagent_advertiser_required, which lists up to 10 granted advertisers by id and name and says how many more there are. An agent with no active grant is refused withagent_no_advertiser_access, and so is a call that names an advertiser it has no grant on. Nothing is remembered between calls, so one session can work several granted advertisers. - The tools offered follow the grants, not the kind of account the credential belongs
to. When the credential belongs to your organization’s parent account and the agent holds
at least one grant, the V3 endpoint still lists its buyer tools,
get_statusreports abuyeraccount, and each call runs in the account below the parent that owns the advertiser it names. A call that names no advertiser and would act on the parent account itself, such as creating an advertiser or changing billing details, is refused, because no grant covers the parent. The agent can list its granted advertisers without naming one, withsearchof advertisers. An agent with no active grant keeps the parent account’s organization tools. - Seller reads show only granted advertisers. A
sellerorconnectionread lists each advertiser’s activation with that media partner incontrolPlane.activation.advertisers, and a connection lists the advertisers mapped to its accounts. For a buyer agent these lists, their counts and the activation summary cover only the advertisers it is granted; the account’s selection and billing read in full. See Media partner availability. - A buyer agent cannot switch accounts.
switch_accountstays refused for it. - Notification delivery re-checks the grant on every attempt, so revoking a grant also stops that advertiser’s notifications reaching the agent.
- A grant can show fees. If your organization charges clients an operator fee, a buyer
agent sees only the total cost of a buy that carries it, unless the grant for that
advertiser is marked
showsFeeBreakdown.save_buyer_agentdoes not set that mark and keeps one set elsewhere when it replaces an agent’s access. See Operator fees.
Credentials
A credential is how the agent’s software proves who it is. Credentials are managed in the Apostra web app, so the secret never passes through chat: open Settings → API keys → Manage buyer agents. The page shows, for the organization you are signed in to, each agent’s name, connection status, advertiser access and recent activity, and an agent detail page with Overview, Access, Connections, Notifications, Activity and Settings. The page never shows a credential secret. A secret is delivered once, by the response that issues or rotates it, and cannot be retrieved afterwards, not by the console, not by the API and not by support. From the agent’s page an administrator can:- Issue a credential. Apostra creates a new identity-only OAuth client and shows its secret once.
- Register an existing credential. Bind an API key or OAuth client your organization already owns to a new buyer agent. Registering does not change what that credential could already do.
- Rotate an API key. Apostra creates the replacement, shows its secret once, and retires the current key.
- Revoke a credential. It stops authenticating immediately and cannot be registered again.
ISSUANCE_RECONCILIATION_REQUIRED, repeat the same request once the transient failure has
cleared, and do not start another issuance until that retry has settled. If it still
reports that reconciliation is required, keep the request ID and contact support.
The Access tab lets an administrator select exact advertisers and choose Read or
Read and write for each. Settings lets an administrator rename the agent and pause,
resume or retire it, with the same name confirmation as above. Deactivating a single
notification destination or subscriber is also done there, and needs the same retyped name.
Hand off credential setup after building an agent
A coding agent can prepare credential setup for an existing, active external agent that has never had a credential. A directly signed-in organization administrator sendssave_buyer_agent with the agent’s id and credentialHandoff: true. The response carries
credentialHandoff: a non-secret reference, the agent’s principalId, an expiresAt
time, a verificationState, and the ceremonyPath for completing setup. Preparing setup
creates neither a credential nor advertiser access, and the coding agent’s own credentials
stay separate from the runtime’s.
The administrator who prepared the handoff opens ceremonyPath. It opens Settings → API
keys → Manage buyer agents for that agent. The administrator submits the credential form,
receives the secret once, and stores it in the runtime’s protected secret store. Never put
the secret in chat, a coding-agent prompt, source code, logs or Activity. The coding agent
receives only the reference and the verified setup state.
The reference expires after 15 minutes if unused, and the same administrator can prepare
another. It works only for the administrator and organization that prepared it, and for the
agent it names. Read get({ "kind": "buyer_agent", "id": "<principal-id>" }) as that
administrator to check credentialHandoff.verificationState:
Only the administrator who started the handoff sees its reference, and not in search
results or to the runtime. Rotation and revocation stay the way to manage a delivered
credential. Advertiser access still needs its own grants.
What must be ready
Readiness has five independent gates: registration, an active credential, current configuration with recorded proof, the exact advertised capability, and separate business authority. All five must be ready. A principal ID, credential, domain, destination or proof result never satisfies the business-authority gate. These gates do not substitute for one another. Single sign-on authenticates the person who installs or administers the integration, a workload credential identifies the buyer agent, and only an explicit agent-and-advertiser grant authorizes business operations. Spend, payment and Terms authority stay separate. Apostra reports these boundaries and cannot create or approximate a missing grant.Related
- Hosted buyer agents covers hosted orchestrators and an account’s own agent.
- Run Apostra for several client accounts compares buyer agents with other ways to separate clients.
- Sign in a self-built agent covers how an agent obtains its own access.
- Build a reporting pipeline covers the machine notifications an agent subscribes to.