> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Identity documents > Who publishes what, where it lives, and how publisher authorization differs across hosted ad-server, modular, linked, and external-agent source models. Apostra does not own your identity. You publish it at your own domain, signed with your own keys, on your own clock, and Apostra reads it. The **Agentic Advertising Organization (AAO) registry** fills the gap until you have published, and computes a few things you do not publish yourself. That is the whole model: **owners publish; the registry is a fallback and a compute layer; Apostra reads and trusts what is there.** This page answers "what are all these documents, and how does Apostra use them?" The short version: **registration gates connection; authorization is controlled by the publisher and shown as an advisory signal; compliance informs.** This is not a credential-management page. Buyer-agent API keys and identity-only WorkOS machine credentials identify an automation to Apostra. They do not publish, replace or authorize `adagents.json`, `brand.json` or an agent card. See [Buyer agents](https://docs.apostra.com/v3/buyer-agents.md) for that workflow. ## Storefront operator vs. publisher domains A storefront has one **operator domain**: the legal or operating entity that runs that storefront. Choose its scope to match the storefront. A regional storefront uses the regional entity's domain, and a storefront that is truly group-wide uses the parent group's domain. Create separate storefronts when regions need separate operators, commercial rules or administration. The sites and titles sold through that storefront remain **publisher domains**. They do not replace the operator domain. Each publisher authorizes the sales agent in its own `adagents.json`. Those files can be small pointers to one centrally maintained document, so a group does not need to copy the same full configuration into every title's file. [Which domain is which](https://docs.apostra.com/v3/domains.md) explains how the operator domain is verified. ## The three documents Three identity documents matter, each **owned and published by a different party**. The AAO registry is not one of them; see below. | Document | Who owns it | Where it lives | What it answers | | - | - | - | - | | **`adagents.json`** | The **publisher** | `https:///.well-known/adagents.json` | Two things: **which agents are authorized** to sell the publisher's inventory (and over which properties), and **what inventory the publisher has**: AdCP collections, placements and creative formats. | | **`brand.json`** | The **brand or operator** | `https:///.well-known/brand.json` | Which agents the brand **owns and runs** (by role), where their signing keys live, and the corporate **hierarchy** (house or parent brand). | | **Agent card** (`get_adcp_capabilities`) | The **agent itself** | The agent's own endpoint | What the agent **claims it can do**: the AdCP capabilities it supports. | > [!NOTE] > > The `brand.json` that lists an agent belongs to whoever **runs that agent**. An agency > named as `operator` on a buyer's account is a different party: it does not list or > vouch for the buying agent that calls you. To verify a signed request, find the > agent's keys from the agent's own URL; see [Verifying our signed > requests](https://docs.apostra.com/v2/authentication.md#verifying-our-signed-requests). > [!NOTE] > > The **`ads.txt` `managerdomain`** entry is a legacy one-hop bridge. A network-managed > publisher that hosts no `adagents.json` of its own, such as a Raptive or CafeMedia > managed domain, delegates to its manager's file. Apostra resolves this automatically. > [Publisher adagents.json entry](https://docs.apostra.com/v3/seller-publisher-adagents.md) covers how the file is > found and what each authorization reason means. ### The AAO registry is not a document The registry is a source and compute layer over those documents. It does four things: 1. **Computes compliance.** It grades an agent's self-declared capabilities against AAO test storyboards and publishes a verdict: `passing`, `pending`, `degraded` or `failing`. The agent does not publish this. The registry computes it. 2. **Hosts a community mirror** of a publisher's `adagents.json` so a publisher that has not published is still discoverable. A community mirror lists no authorized agents. It exists to be *found*, never to *authorize*. An empty mirror is not a denial. 3. **Hosts publisher-managed AAO copies** when a publisher chooses an AAO-hosted setup. The publisher still proves authority from its own domain by serving an `authoritative_location` stub that points at the AAO-hosted document. 4. **Carries discovery metadata** (`discovery_method`, `hosting.mode`) saying whether a record is owner-published or a community fallback. Publisher creative formats in storefront adapters follow the same ownership rule. They are published as URL-free `format_kind` and `format_options` declarations under the publisher domain, for example Snapchat's under `snapchat.com`. An adapter does not create a separate Apostra creative-agent URL or format namespace. Tenant-local templates such as Figma frames use only their base `format_kind`; they do not create a synthetic publisher catalog. AudioStack likewise uses the standard `audio_hosted` kind directly, with an exact duration in `params.duration_ms_exact` when needed, and has no separate AudioStack format namespace. For retail-media technology platforms, the retailer owns the publisher catalog under the retailer's domain. The technology vendor's domain is not a substitute. A self-published document always supersedes the community fallback, and the registry resolves that. AAO-hosted records converge only after the publisher-origin well-known URL is reachable and verifies the hosted document. Apostra trusts what the registry returns, and uses the hosting metadata to explain which setup state a record is in. ## Gates vs. signals An agent being **AAO-compliant** ("did it pass the test suite?") is a different question from an agent being **authorized to sell a publisher's inventory** ("does that publisher's `adagents.json` list it?"). They have different owners, different documents and different consequences. **One thing blocks setup: agent registration. Everything else is a signal during setup and product authoring.** * **Authorization is publisher-controlled.** A sales agent must be **registered** with AAO before it can be connected as an inventory source. Publisher authorization is separate: that publisher's `adagents.json` says which agent may sell which properties. Apostra resolves it and shows a warning when it is missing. It does not block a source connection, product authoring or activation. * **AAO compliance informs.** The registry's compliance verdict is advisory. A non-passing verdict shows as a prominent warning, but it does not stop your storefront going live or transacting. You can sell while compliance is still pending. | Moment | What is checked | Blocks? | | - | - | - | | **Connect a source** | The agent is **registered** with AAO. | **Yes.** An unregistered agent cannot be connected, and the refusal carries `details.reason: "agent_not_in_aao_registry"`. A registry that cannot be reached is a "try again", not a "no". | | **Go live** | The AAO **compliance** verdict. | **No.** A non-`passing` verdict shows as a warning and never holds back go-live. | | **Author products and set up publisher references** | The publisher's `adagents.json` **authorizes** this agent for the inventory. | **No.** Apostra warns when a resolved publisher file does not authorize the agent, then lets setup and product authoring continue. | So "your AAO compliance is pending" does not mean "you cannot go live". It is an advisory you can act on at your own pace. "This publisher has not authorized the agent" is a publisher-owned authorization problem to fix before you depend on that inventory. It is not a reason to stop setup or product drafting. ### Registering your agent with AAO Only a sales agent you connect yourself needs to be in the AAO registry. If Apostra hosts your agent (a Storefront account), there is nothing to do. If you connect your own agent, the registry must be able to find it, in one of two ways. Neither needs a paid AAO membership: * **Declare it on your own domain.** List the agent in the `agents` of your [`brand.json`](https://docs.adcontextprotocol.org/docs/brand-protocol/brand-json), or in your [`trust.json`](https://docs.adcontextprotocol.org/docs/reference/trust-json). * **Add a community entry** for it in the AAO registry, with an AgenticAdvertising.org account. If a vendor or platform runs the agent for you and has already done this, you have nothing to do. Apostra charges nothing for AAO. ## Why Apostra asks for AAO, and what it does with it Apostra reads the registry to confirm that an agent you connect is a real, registered participant, to show you its compliance verdict as a signal, and to discover the publishers and brands tied to your domain. It does not use the registry as an Apostra allowlist. The registry is the source of truth, and Apostra shows what it says. ## What Apostra publishes for you, and what it never will Apostra reads your **inventory identity** (your formats, placements and AdCP collections) live from the `adagents.json` you publish, and shows it, so a publisher that is in the registry is discoverable. You publish upstream and Apostra picks it up: host your own `adagents.json` and `brand.json`, and Apostra reads them live. Re-check a domain after you update the file. Apostra reads a brand's corporate hierarchy (`house`, `keller_type` and `parent_brand`) and shows it. It does not use it to drive business rules such as rate cards across a brand family. Apostra **never** touches your **authorization**. It does not mint or edit the `authorized_agents[]` in your `adagents.json`. Granting an agent the right to sell your inventory is always your act, made in your own document. > **Identity Apostra reads; authorization Apostra only ever references.** If the registry reports `hosting.mode: "aao_hosted"` for a publisher that has started self-hosting, check the publisher-origin well-known URL first. The queried domain's `https:///.well-known/adagents.json` must be crawler-accessible and must return either the full file or a valid pointer to the authoritative file. A JSON file that only works from a browser, only works on `www.`, or blocks non-browser crawlers is not treated as validated self-hosting. ## How networks and managed publishers are represented A network or SSP that sells across many publisher domains it does not own, and a publisher that hosts no file of its own, still fit this model through **delegation**, not self-declaration. A network cannot host a file on its own domain claiming it sells someone else's inventory, because authorization is always the domain owner's act. Instead: 1. **The network publishes one manager `adagents.json`** on a domain it controls, listing its agent or agents and the publishers it represents. This is the `adagents.json` model applied to the network's own domain. 2. **Each publisher delegates to the network**, in any one of these ways: * an `ads.txt` `MANAGERDOMAIN=` line, a one-line delegation, with the publisher hosting no `adagents.json` of its own (the Raptive and CafeMedia pattern); * an `authoritative_location` pointer in the publisher's own `adagents.json` that redirects one hop to the network's centrally hosted file; or * a `delegated` or `ad_network` `delegation_type` entry in the publisher's `adagents.json` (see the [glossary](https://docs.apostra.com/v2/concepts/glossary.md)). Apostra resolves all three live, so once a publisher delegates, the network's whole managed footprint is discoverable with no per-publisher file authoring. ### Changing from a modular source to an external agent Replacing a modular source with your own external sales agent changes which publisher authorization applies. It does not retroactively make the modular source an Apostra authorization case. A modular source needs publisher `adagents.json` authorization only when its module or execution path exposes a publisher-facing agent URL. Once an external AdCP sales agent becomes the source, publishers authorize that external agent's URL before the seller depends on that inventory. A modular source's spreadsheet contract stays with the modular source, including its legacy collection identifiers and net impressions-capacity fields. Those inputs do not change this authorization boundary. See [Modular source pages](https://docs.apostra.com/v3/seller-modular-source-pages.md). More generally, for source families that sell publisher inventory through an agent URL, the URL a publisher authorizes depends on the storefront's source model. If the seller connects its ad server directly to Apostra and uses Apostra's hosted storefront agent, publishers authorize the canonical Apostra storefront agent URL, `https://interchange.io`. Linked storefront inventory uses the upstream storefront's own authorization model. For network-managed publishers, put that authorization in the manager's file and have publishers delegate to it through `MANAGERDOMAIN` or `authoritative_location`. If a publisher also hosts a direct `adagents.json` that points somewhere else, that direct file can shadow the manager-domain fallback. The fix is to restore delegation: make the publisher file point to the same manager file, or remove the publisher file so its `ads.txt` `MANAGERDOMAIN` delegation is used. The delegation itself, that one `ads.txt` line or `adagents.json` entry, is the publisher's **authorization** act, and it is the only step that has to start with the domain owner. A network can guide its publishers to add it, but Apostra never mints it for them. A network cannot make itself authorized for inventory whose owner has not delegated. ## Related * [Publisher adagents.json entry](https://docs.apostra.com/v3/seller-publisher-adagents.md) says what to put in a publisher's file and what each authorization reason means. * [Which domain is which](https://docs.apostra.com/v3/domains.md) explains the registered, brand and publisher domains. * [Connect an agent](https://docs.apostra.com/v3/connect-an-agent.md) covers registering and connecting a sales agent. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.