feat(aao): inverse-lookup endpoint — given agent_url, return authorizing publishers

[bokelley]

Background

The AdCP Python SDK currently exposes two authorization-check primitives:

• Push (publisher → agent): verify_agent_authorization(adagents_data, agent_url, ...) — given a parsed adagents.json, is this agent listed?
• Pull, with caller-supplied list (agent → known publishers): fetch_agent_authorizations(agent_url, publisher_domains=[...]) (adcp-client-python adagents.py:1306) — caller passes a list of publisher_domains, SDK fetches each one and returns the subset that authorize the agent.

Neither answers the question every sales agent operator actually needs at sync time:

"What publishers have authorized my agent?"

Today operators have to either (a) maintain the publisher_domain list manually and call fetch_agent_authorizations against it, or (b) crawl the open web. Both are infeasible at scale.

Concrete trigger

Raptive (managed by CafeMedia, ~6,800 owned-and-operated domains) all delegate authorization to a single cafemedia.com adagents.json via either ads.txt MANAGERDOMAIN=cafemedia.com or adagents.json authoritative_location. The SDK's chain-following discovery handles per-domain verification correctly — but for a sales-agent operator onboarding Raptive, there's no way to discover the 6,800-domain set without either:

1. Asking CafeMedia to hand over a spreadsheet (manual, stale)
2. Building a per-domain bulk-import UI (papers over the missing primitive)
3. Crawling DNS / ads.txt across the web

The AAO directory at agenticadvertising.org is already indexing publisher adagents.json files. It has the inverse map — it just doesn't expose it.

Proposal

Define an AAO directory inverse-lookup endpoint and add the corresponding SDK client function.

Endpoint shape (strawman)

GET https://{aao_directory}/v1/agents/{agent_url_encoded}/publishers
GET https://{aao_directory}/v1/agents/{agent_url_encoded}/publishers?since={iso8601}  # incremental sync

Response:

{
  "agent_url": "https://sales-agent.example.com",
  "directory_indexed_at": "2026-05-19T12:00:00Z",
  "publishers": [
    {
      "publisher_domain": "cooking.com",
      "discovery_method": "ads_txt_managerdomain",
      "manager_domain": "cafemedia.com",
      "authorized_properties_count": 12,
      "total_properties_count": 12,
      "status": "authorized",
      "last_verified_at": "2026-05-19T08:00:00Z"
    },
    {
      "publisher_domain": "wsj.com",
      "discovery_method": "direct",
      "authorized_properties_count": 47,
      "total_properties_count": 200,
      "status": "authorized",
      "last_verified_at": "2026-05-19T10:00:00Z"
    }
  ],
  "next_cursor": null
}

Mirrors the existing discovery_method / manager_domain fields on AdAgentsValidationResult so operators get the same provenance they already use for direct verification.

Status semantics

Reuse PublisherPartnerStatusKind-style discriminators that consumers like the Prebid Sales Agent already implement against:

• authorized — typed binding resolves to ≥1 property
• unbound — bare entry, top-level properties present (permissive resolution)
• pending — agent listed but selector resolves to nothing, or not listed but file is fetchable

Excludes unreachable and no_properties — the directory only indexes publishers whose adagents.json was successfully fetched and references the agent.

Out of scope

• Authentication on the directory (publishers are public; if rate-limiting is needed, key on agent_url with a public key proof — separate RFC)
• Cross-directory federation
• Push notification of new authorizations (poll-based v1 is fine)

Work items

• Define endpoint shape in the AAO directory portion of the spec (path, params, response schema)
• Define how discovery_method = ads_txt_managerdomain interacts with the salesagent#377-style warning that manager-domain authorizations must verify the source publisher is named in the manager's adagents.json
• Companion SDK feature request in adcp-client-python — fetch_agent_authorizations_from_directory(agent_url, directory_url, ...)

References

• Salesagent issue blocking on this: prebid/salesagent#511 — being closed in favor of this upstream solve
• Existing per-domain pull API: adcp/adagents.py:1306 fetch_agent_authorizations
• Existing single-domain discover-and-validate with provenance: adcp/adagents.py:676 validate_adagents_domain

[bokelley]

Triage

Classification: Feature request
Bucket(s): registry / discovery, spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: endpoint shape is directionally sound and non-breaking (additive, minor bump); blocker on unbound/pending status values — no backing data in catalog_agent_authorizations today, so the directory can only return publishers it has confirmed authorized; field naming diverges from established properties_authorized/properties_total convention on the forward direction.
• adtech-product-expert: operator pain is real, layer (directory, not SDK) is correct; blocker on authorized_properties_count/total_properties_count — "total" on a managed-network file is network-wide, making 12/12 look like full authorization when it may mean 12 of 6,800 network properties; add adagents_authoritative as a third discovery_method value to distinguish authoritative_location hops from ads_txt_managerdomain and direct.

My take: Both experts converge on the direction being right and the indexed data being queryable today; the two schema blockers below need a call before spec text lands. Publishing this endpoint also creates an implicit crawl-freshness commitment — a normative last_verified_at field plus a documented crawl-interval SLA should gate GA.

@bokelley, two decisions before spec draft:

---

Decision 1 — Status enum: authorized-only or full taxonomy?

Option A — authorized-only (ship with what the directory has today):

  "status": "authorized"
- // drop unbound + pending — directory returns only confirmed-authorized publishers

Clean guarantee for v1; operators know every row is verified. No new crawler state required.

Option B — full taxonomy (requires new crawler state):

  "status": "authorized" | "unbound" | "pending"
+ // needs new state columns + crawl-queue logic before spec can be normative

---

Decision 2 — Properties count: drop or scope to this publisher?

Option A — drop the ratio (avoids misleading managed-network math):

- "authorized_properties_count": 12,
- "total_properties_count": 12
  "status": "authorized"

Option B — replace with placement count scoped to this domain only:

{
  "publisher_domain": "cooking.com",
  "authorized_placement_count": 12,
  "status": "authorized"
}

authorized_placement_count = placements under cooking.com specifically the agent is authorized for — not network-wide.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01GEUR54L7iHujwYakSENwWd

---

Generated by Claude Code

[bokelley]

Decisions on the triage open questions

Both triage decisions are good catches. Resolving as follows.

Decision 1 — Status enum: authorized + revoked for v1

Going with the triage's Option A direction, slightly extended: scope the v1 enum to authorized and revoked only. unbound and pending both presuppose crawler state the directory doesn't have today (and pending in particular requires snapshot semantics around publishers whose files we've fetched but don't list this agent — a separate indexing pass). Ship what's queryable; leave room to add states later.

revoked is cheap to surface: when a publisher's adagents.json newly lists this publisher_domain in revoked_publisher_domains[] (the lifecycle field added in the managed-network-scale changeset), the directory emits one tombstone row on the next sync after the revocation lands, then drops it. Operators get the propagation signal without polling the publisher's cache TTL.

- "status": "authorized" | "unbound" | "pending" | "revoked"
+ "status": "authorized" | "revoked"

Decision 2 — Counts: keep them, scope per-publisher

The triage flagged that authorized_properties_count: 12 / total_properties_count: 12 reads as "fully authorized" but on a managed-network parent file is 12 of 6,800 network properties. Real concern, but the right fix isn't to drop counts — the directory's whole value-add is that it ran the resolution once so operators don't all hammer 6,800 publishers in parallel. If the directory only points operators at publisher files to verify directly, it adds little over a per-operator crawl.

Fix is naming + scoping. Both counts are about this row's publisher only, never network-wide:

- "authorized_properties_count": 12,
- "total_properties_count": 12,
+ "properties_authorized": 12,
+ "properties_total": 12,

• properties_authorized — properties under this publisher_domain the agent's selector resolves to
• properties_total — properties under this publisher_domain in the publisher's file (or the parent file's inline subset for that domain, per feat(adagents): clarify publisher_properties resolution — managed-network pattern needs inlined-properties path #4825)

So recipeswithessentialoils.com returns { properties_authorized: 1, properties_total: 1 }, and the operator sees 6,800 such rows summing to the network total — correct mental model, no ambiguity.

This makes #4825 a hard dependency, not a soft one: the directory cannot compute properties_total for cafemedia-shape publishers without the inline-resolution rule. Federated-only resolution means 6,800 HTTP fetches per directory refresh — the same scale problem operators have, just moved one layer up.

Additional changes from expert review

• Add adagents_authoritative as a third discovery_method value, distinct from ads_txt_managerdomain and direct. The two paths have different safety semantics (authoritative_location is publisher-declared in their own file; managerdomain is ads.txt-declared) — operators want to see which path got them in.
• Add signing_keys_pinned: bool per row. Cheap to surface, useful at sync time: tells the operator whether this publisher pins their JWKS, which is the signal that the agent's published keys must match. No new crawler state required.

Revised response shape

{
  "agent_url": "https://sales-agent.example.com",
  "directory_indexed_at": "2026-05-19T12:00:00Z",
  "publishers": [
    {
      "publisher_domain": "recipeswithessentialoils.com",
      "discovery_method": "ads_txt_managerdomain",
      "manager_domain": "cafemedia.com",
      "properties_authorized": 1,
      "properties_total": 1,
      "signing_keys_pinned": false,
      "status": "authorized",
      "last_verified_at": "2026-05-19T08:00:00Z"
    },
    {
      "publisher_domain": "wsj.com",
      "discovery_method": "direct",
      "manager_domain": null,
      "properties_authorized": 47,
      "properties_total": 200,
      "signing_keys_pinned": true,
      "status": "authorized",
      "last_verified_at": "2026-05-19T10:00:00Z"
    },
    {
      "publisher_domain": "former-partner.example",
      "discovery_method": "authoritative_location",
      "manager_domain": "cafemedia.com",
      "properties_authorized": 0,
      "properties_total": 0,
      "signing_keys_pinned": false,
      "status": "revoked",
      "last_verified_at": "2026-05-19T11:00:00Z"
    }
  ],
  "next_cursor": "eyJv..."
}

Endpoint shape (unchanged)

GET https://{aao_directory}/v1/agents/{agent_url}/publishers
GET https://{aao_directory}/v1/agents/{agent_url}/publishers?since={iso8601}
GET https://{aao_directory}/v1/agents/{agent_url}/publishers?cursor={opaque}
GET https://{aao_directory}/v1/agents/{agent_url}/publishers?limit={n}

{agent_url} percent-encoded; canonicalization (lowercase host, default port stripped) applies on lookup, matching the SDK's verify_agent_authorization convention.

HTTP semantics

Status	Meaning
200 OK	Lookup succeeded; body MAY have empty publishers[].
400	Malformed agent_url, invalid cursor.
404	Directory has never indexed any publisher referencing this agent_url. Distinct from 200 + empty (we've indexed this agent, no current authorizations resolve).
429	Rate limit. Retry-After set. Bucket key: agent_url + IP.
5xx	Retry with backoff.

Cache-Control + ETag set; conditional GET (If-None-Match) is the wire-level cache mechanism. directory_indexed_at in the body is the freshness anchor.

Work items

• Schema at static/schemas/source/aao/agent-publishers.json
• Docs at docs/aao/directory-api.mdx
• Resolve feat(adagents): clarify publisher_properties resolution — managed-network pattern needs inlined-properties path #4825 before publishing properties_total on managed-network-shape files
• SDK wrappers: adcp-client-python#746, adcp-client (TS), adcp-go, adcp-sdk-java
• Endpoint implementation in directory server (out of this repo)
• Changeset: feat(aao): directory inverse-lookup endpoint for agent → publishers

Out of scope for this RFC

• Authentication (publishers are public; rate-limit graduates to identity-based via RFC 9421 signing in a separate RFC if needed)
• Cross-directory federation
• Push notification of new authorizations (poll-based v1 is fine)
• ?include=properties for inline property detail (counts-only v1; add later if operators ask)

[bokelley]

Triage

Classification: Feature request (RFC — decisions resolved)
Bucket(s): registry / discovery, spec / protocol
Status: deferred

Decisions accepted. authorized | revoked enum, per-publisher properties_authorized / properties_total, adagents_authoritative discovery method, and signing_keys_pinned per row are the spec'd shape. HTTP semantics and cursor pagination are well-specified.

Blocked-on: #4825 — resurfaces on merge. The directory's properties_total computation for managed-network-shape publishers (inline-with-publisher_domain resolution path) can't be normative until the spec endorses that resolution path. Once #4825 lands, the PR surface is static/schemas/source/aao/agent-publishers.json + docs/aao/directory-api.mdx — both non-breaking additions, minor-bump.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01EsBD1t25Yucq4yR3GyZioc

---

Generated by Claude Code