Connect your sales agent

This page is for a seller bringing their own AdCP sales agent into Apostra as supply — how Apostra uses the Ad Context Protocol (AdCP) to connect your agent as a storefront inventory source.

​

Ways inventory comes in

A storefront draws supply from one or more sources:

• AGENT — an external AdCP-compatible sales agent Apostra connects to. This is the “bring your own agent” path and the focus of this page.
• MANAGED_SALES_AGENT — an operator-owned ad server with Apostra-managed sales-agent plumbing.
• LINKED_STOREFRONT — wholesale inventory from the pool of listed, transacting storefronts.
• MODULAR_SOURCE — composed from private modules (avails, booking, trafficking, reporting).

See Choosing a source for the full comparison.

​

What you bring (external AGENT)

There are two parts: the technical setup for your agent, and bringing the inventory it sells.

​

1. Technical setup

1. A conformant AdCP agent endpoint that advertises its supported_protocols and versions via get_adcp_capabilities. Apostra supports AdCP 3.0 and 3.1 — see AdCP versioning & negotiation for how the version your agent serves is negotiated. If you discovered the agent from a publisher, use the executable URL in AAO’s selected authorized_agents[].url entry. The publisher’s adagents.json, AAO hosting.resolved_url, and an authoritative_location are identity-document locations, not agent endpoints.
2. Signing keys (JWKS) — set up your request/webhook signing keys so Apostra can verify your agent’s RFC 9421-signed calls and you can verify ours. This is a required step, not an afterthought, if you sign with RFC 9421 — for webhook verification specifically, Apostra discovers your JWKS through brand.json → agents[].jwks_uri (see item 5 below), not a standalone jwks.json URL. See Authentication.
3. Credentials for authenticating to your agent endpoint.
4. Real-time targeting (TMP), if you serve through it — connect the TMP Router so serve-time targeting and macros resolve. See Real-time targeting.
5. A brand.json at /.well-known/brand.json on your agent’s origin. Optional if you never sign or verify over RFC 9421 — but required the moment you do: it’s how Apostra resolves the JWKS for verifying your RFC 9421-signed webhook deliveries (e.g. the storefront-catalog invalidation webhook). Also brands the agent as operator-owned (“I own this agent”) for identity purposes.

For OAuth sources, the standards path is MCP OAuth protected-resource discovery at the endpoint’s well-known URL. That document advertises at least one authorization_servers issuer, and the issuer publishes RFC 8414 authorization-server metadata (or OpenID configuration) containing its authorization and token endpoints. The authorization server may use a different origin from the agent. If an older gateway validates a resource-specific token audience but does not publish protected-resource metadata, set oauthAudience while registering a new OAuth identity or updating an existing source. Apostra sends that same public URI as both the Auth0 audience and RFC 8707 resource and stores it with the OAuth configuration. Update returns a fresh authorization URL for consent when discovery and flow storage succeed; a successful response without oauth means the audience was stored and the same update should be retried to start consent. Create returns a URL only for a newly registered identity when discovery and flow storage succeed. If that block is absent, use Start agent OAuth after creation; retrying create reuses the identity and does not initialize consent. If the endpoint reuses an existing identity, create reuses that identity’s OAuth configuration instead. Omit the override when protected-resource discovery supplies the resource. The override does not replace authorization-server metadata: an older agent must still publish that metadata directly on its own origin. Every discovered network destination must resolve to a public endpoint; private, loopback, link-local, or unresolvable destinations are rejected. An explicit audience is a resource identifier rather than a URL Apostra fetches, but it must still be a public HTTPS URI and cannot name a private or local address. Apostra delegates discovery, dynamic client registration, PKCE/state, and authorization-code exchange to the AdCP client SDK.

​

Connect it in Apostra

In any MCP Apps host, call prepare_external_sales_agent_connection to open the focused Connect sales agent Task. Enter the endpoint, protocol, and credentials inside that secure surface; credentials are never passed through the model. The first version offers no authentication, bearer token, and basic authentication—the methods the existing sales-agent runtime executes without a provider-specific adapter. The shared connection-definition model also supports typed API-key, OAuth 2.0, JWT, and platform-service-account methods for integrations that declare and implement them; it never accepts custom executable header templates. After connection, use Source diagnostics for compliance, discovery, and health checks. The Task pins the version of the connection definition used for setup. Existing API clients that do not send a connection definition continue through the legacy request shape while integrations migrate. In both paths, credentials belong to your storefront account: Apostra stores the secret in its credential store, keeps only a client-scoped reference in connection metadata, and returns only whether credentials are configured. Secret values and secret references are never returned to the Task or model.

​

2. Bringing inventory — onboard your publishers

You don’t hand Apostra a separate list of formats and inventory — that comes from onboarding the publishers your agent sells for. For each publisher (that’s you if you’re a publisher; each partner if you’re a sales house or network), that publisher’s properties must authorize your agent:

• An adagents.json lives on the publisher’s domain (not necessarily yours) and authorizes your agent for that publisher’s properties. Properties can be non-web (CTV, audio, app, DOOH), so this is about properties, not just websites.
• Authorization is tied to the publisher domain — an agent is authorized only for properties a publisher has granted it (presence in authorized_agents[] alone isn’t sufficient).
• A publisher’s adagents.json is also where their placements, formats, and other property details are declared.

So a sales house representing 50 publishers needs each of those 50 publishers’ domains to authorize the agent — the authorization is per-publisher, across all your partners.

​

Conformance: understand the AAO signal

The AAO registry is the source of truth for agent registration and compliance verdicts. Apostra reads those registry results; it does not define AAO storyboards itself. What “compliance” means operationally: your agent should pass the AAO storyboards for the kind of agent you are. A sales agent passes the base sales-agent storyboard plus the ones for what you sell — guaranteed, non-guaranteed, retail, and so on. Apostra uses AAO signals in three different ways:

• Registration is a connect-time gate. An external AGENT source must be registered with AAO before it can be connected.
• Compliance is advisory for source connection and storefront activation. A non-passing verdict is surfaced as a warning, but it does not block going live.
• Marketplace listing is a separate Apostra review step after activation. AAO compliance is an important signal in that review, but it is not the same thing as the activation gate.

See Storefront onboarding for the connect-time table and Storefront overview for marketplace review.

​

Product format compliance

Product format compliance is separate from the AAO storyboard verdict. A product may publish URL-free canonical format_options[] or an exact legacy {agent_url, id} reference that Apostra’s compatibility mapping can resolve. Exact legacy references remain supported without a sunset; Apostra never guesses from the ID text. When canonical-format compliance is enabled for your storefront, **Seller Setup

Inventory sources** flags unresolved catalog products from active external sales-agent sources and names the affected source and count. A product from an existing or newly connected source passes when it publishes at least one usable canonical option. For a legacy product with multiple references, Apostra keeps every successfully projected option and reports an unsupported remainder as an advisory; one unsupported reference does not suppress the product. A product with no usable canonical option is withheld on its own until corrected. Neither case implicitly changes Source request eligibility or storefront transaction eligibility.

Catalog age is handled by the separate refresh policy: an interpretable declaration does not become noncompliant when its cache entry ages. Because pass-through get_products responses are brief-specific, Seller Setup uses a source’s public catalog evidence when it is available and otherwise falls back to its account-conditioned evidence. The newest declaration for a product replaces older observations across the wholesale and pass-through paths. Buyer discovery and purchase still recheck the relevant account context and selected product before serving. Replace an unsupported seller-specific reference with an exact shared-catalog reference or publish an interpretable custom canonical declaration. Managed and modular sources continue to use their own readiness contracts. When a source has no persisted product declarations, a buyer brief can still perform a non-serving source revalidation: Apostra returns no products from that source on the call but records the relevant public or account-conditioned catalog evidence. A corrected product with the same ID clears the diagnostic on the next readiness evaluation. A later response containing only interpretable products also replaces an older pass-through observation whose products are no longer returned for that brief. Cache age never turns a valid declaration into a failure.

​

How your agent participates (the AdCP surfaces we use)

Which surfaces light up depends on the storyboards your agent passes (above). Once connected, Apostra uses these AdCP surfaces against your agent:

​

What your sync_creatives acknowledgement tells the buyer

Apostra reports a creative as live to the buyer only from what your agent says about it. Per creative, the acknowledgement carries: status is optional in AdCP, and is read as advisory: if you run no review lifecycle, omit it and an accepted action stands on its own. If you do hold creatives for review, you must send status — an omitted status cannot mean both “no review gate here” and “still waiting on mine”, and Apostra reads the first. Sending it is the difference between the buyer knowing a creative is waiting on you and the buyer assuming it is ready to serve. If a creative is suspended or archived on your side, say so — that is what stops a buyer from counting it as delivering inventory. Wholesale product and signal catalog requests are used only for a Source that supports the Storefront-built path and whose Agent reports AdCP 3.1+ support. An Agent-supplied Source instead receives buyer discovery and media-buy calls through the normal surfaces above. An Agent may support both product paths, in which case each Source selects one or both. These paths are not separately monetized and are not inferred from endpoint behavior or catalog contents. The provider declaration and any both-path selection are currently reconciled by Apostra support; the Source page displays them read-only. If diagnostics report a missing declaration or incomplete wholesale contract, correct the Agent’s product, property, format, pricing, and execution data, then ask Apostra support to refresh or reconcile the capability. You can monitor your source’s live behavior — per-call outcomes, errors, and latency — in Inventory-source diagnostics.

​

Governance agents

A buyer can bring their own governance agent — an external service that validates campaign actions (budget, brand safety, regulatory compliance) before they execute — and Apostra supports this. We will support third-party governance agents; a buyer doesn’t depend on us to provide one. What that means for you as a seller: support the AdCP governance protocol so you can transact with governance-enabled buyers. When a buyer’s governance agent is in play, your agent calls check_governance to validate each action and fulfills as approved. The governance agent — not you — holds the consolidated audit trail. (Campaign governance is an evolving AdCP surface; see the FAQ for credentials and audit.)

​

FAQ

Questions sellers ask when integrating. Each answer is what AdCP defines (the protocol’s source of truth) plus what Apostra does today (the delta).

​

Where the truth lives