RFC: ads.txt managerdomain fallback for adagents.json discovery
Summary
Add an optional one-hop discovery fallback for adagents.json using the managerdomain declaration in a publisher’s ads.txt
Today, validators discover agent authorization data at:
https://{publisher}/.well-known/adagents.json
If that URL returns 404, validators MAY consult:
https://{publisher}/ads.txt
and look for a managerdomain declaration. If exactly one eligible manager domain is found, validators MAY attempt discovery at:
https://{managerdomain}/.well-known/adagents.json
This is intended as a compatibility affordance for publisher-manager topologies where a publisher delegates ad sales, monetization operations, or agent authorization administration to a manager domain.
Motivation
Many publishers in managed-network, wrapper, and SSP-managed inventory arrangements do not directly host their own adagents.json. Instead, a managing entity is responsible for operational ad sales infrastructure and may be the natural host for agent authorization data.
Without a fallback, validators that receive 404 from the publisher’s canonical /.well-known/adagents.json path treat the publisher as missing authorization data entirely, even when the publisher has already declared a manager relationship in ads.txt.
This proposal lets validators use an existing publisher-controlled signal, managerdomain, to locate authorization metadata one hop away, while preserving conservative failure behavior.
Proposal
When validating adagents.json for a publisher domain:
- Attempt canonical discovery first:
https://{publisher}/.well-known/adagents.json
-
If the canonical URL returns 200, process it normally. No fallback is used.
-
If the canonical URL returns 404, the validator MAY fetch:
https://{publisher}/ads.txt
-
The validator MAY parse managerdomain entries from ads.txt.
-
If exactly one eligible managerdomain entry remains, the validator MAY attempt:
https://{managerdomain}/.well-known/adagents.json
-
If the manager-domain file validates, the validator MAY treat it as the discovered authorization source for that publisher lookup.
-
If the fallback fails, the publisher should be treated as missing adagents.json, the same as if no fallback existed.
Accepted managerdomain forms
Validators SHOULD recognize both of the following forms:
MANAGERDOMAIN=example.com
and the legacy/comment compatibility form:
# managerdomain=example.com
Key matching SHOULD be case-insensitive. For example, all of these should be treated equivalently:
MANAGERDOMAIN=example.com
managerdomain=example.com
ManagerDomain=example.com
# managerdomain=example.com
The value should be interpreted as a host token, not a URL. For example:
MANAGERDOMAIN=manager.example
is valid, while:
MANAGERDOMAIN=https://manager.example
should not be treated as an eligible manager-domain value.
Safety rules
Canonical location remains primary
The canonical location remains:
https://{publisher}/.well-known/adagents.json
The fallback only applies when that URL returns 404.
The fallback MUST NOT replace, override, or take precedence over a valid publisher-hosted adagents.json.
Only trigger fallback on 404
Validators SHOULD only attempt the ads.txt manager-domain fallback when the publisher’s canonical adagents.json URL returns 404.
Validators SHOULD NOT use this fallback for other HTTP statuses such as 500, 403, timeout, malformed JSON, or validation failure.
One hop only
The fallback MUST be limited to one hop:
publisher -> managerdomain
Validators MUST NOT recursively follow managerdomain declarations from the manager domain’s own ads.txt.
Cycle detection
Validators SHOULD track visited domains during discovery and MUST avoid cycles.
For example, if:
publisher.example/ads.txt
MANAGERDOMAIN=publisher.example
the fallback should be ignored.
Ambiguity fails closed
If more than one eligible managerdomain entry remains after parsing and opt-outs, validators MUST abort fallback rather than guessing which manager to trust.
Example:
MANAGERDOMAIN=manager-a.example
MANAGERDOMAIN=manager-b.example
In this case, the validator should not fetch either manager domain’s adagents.json.
#noagents opt-out
A managerdomain line MAY include a trailing comment containing the token noagents, case-insensitively, to exclude that manager-domain entry from adagents.json fallback discovery.
Example:
MANAGERDOMAIN=manager.example #noagents
or:
MANAGERDOMAIN=manager.example #NOAGENTS
Validators MUST ignore manager-domain entries marked with #noagents.
This allows a publisher to declare a manager relationship for ads.txt purposes while explicitly preventing that entry from being used for adagents.json discovery.
No success by silence
If the manager-domain lookup fails, returns a non-200, returns invalid JSON, or does not validate as a valid adagents.json, validators MUST treat the publisher as missing adagents.json.
Fallback failure should not be interpreted as authorization.
Example
Publisher does not host adagents.json:
GET https://publisher.example/.well-known/adagents.json
404 Not Found
Publisher’s ads.txt contains:
MANAGERDOMAIN=manager.example
Validator may then attempt:
GET https://manager.example/.well-known/adagents.json
If that file validates, the validator may use it as the authorization source for the publisher lookup.
Non-goals
This proposal does not:
Change the canonical adagents.json location.
Require publishers to use managerdomain.
Require validators to implement fallback behavior.
Permit recursive or multi-hop discovery.
Treat ads.txt as an authorization file by itself.
Allow multiple manager domains to be tried in priority order.
Authorize agents when no valid adagents.json is found.
Compatibility
This is backwards-compatible.
Publishers already hosting /.well-known/adagents.json are unaffected.
Publishers that do not want managerdomain used for adagents.json discovery can either omit managerdomain or mark the relevant entry with #noagents.
Validators that do not implement the fallback will continue to use the canonical discovery behavior.
Suggested validator behavior
A validator implementing this RFC should:
Fetch publisher /.well-known/adagents.json.
If status is 200, validate normally.
If status is 404, fetch publisher /ads.txt.
Parse eligible managerdomain declarations.
Remove entries marked with #noagents.
Abort if more than one eligible manager domain remains.
Abort if the remaining manager domain creates a cycle.
Fetch exactly one manager-domain /.well-known/adagents.json.
Validate the manager-domain file normally.
If valid, report that the authorization source was discovered through ads.txt managerdomain.
If invalid or unavailable, fail as missing adagents.json.
Open questions
-
Should this behavior be described as MAY for validators, or should conforming validators be expected to implement it?
-
Should only IAB directive-form MANAGERDOMAIN=example.com be accepted, or should the comment compatibility form # managerdomain=example.com be formally recognized?
-
Should the #noagents opt-out token be standardized here, or should opt-out be handled another way?
-
Should a validator surface a warning when fallback succeeds, so callers know the source was manager-hosted rather than publisher-hosted?
-
Should the discovered manager-domain authorization file be allowed to authorize inventory for multiple publisher domains, or should additional publisher-domain scoping be required in a future revision?
Reference implementation behavior
PR #4173 implements this behavior in the ADCP validator by adding:
One-hop ads.txt managerdomain fallback on publisher adagents.json 404.
Support for both MANAGERDOMAIN=example.com and # managerdomain=example.com.
Case-insensitive key matching.
#noagents opt-out handling.
Cycle detection.
Ambiguity fail-closed behavior for multiple eligible manager domains.
Unit tests for fallback success, cycles, one-hop depth, #noagents, directive-form parsing, multiple-entry ambiguity, invalid host tokens, and non-404 behavior.
RFC: ads.txt
managerdomainfallback foradagents.jsondiscoverySummary
Add an optional one-hop discovery fallback for
adagents.jsonusing themanagerdomaindeclaration in a publisher’sads.txtToday, validators discover agent authorization data at:
https://{publisher}/.well-known/adagents.jsonIf that URL returns 404, validators MAY consult:
https://{publisher}/ads.txtand look for a managerdomain declaration. If exactly one eligible manager domain is found, validators MAY attempt discovery at:
https://{managerdomain}/.well-known/adagents.jsonThis is intended as a compatibility affordance for publisher-manager topologies where a publisher delegates ad sales, monetization operations, or agent authorization administration to a manager domain.
Motivation
Many publishers in managed-network, wrapper, and SSP-managed inventory arrangements do not directly host their own adagents.json. Instead, a managing entity is responsible for operational ad sales infrastructure and may be the natural host for agent authorization data.
Without a fallback, validators that receive 404 from the publisher’s canonical /.well-known/adagents.json path treat the publisher as missing authorization data entirely, even when the publisher has already declared a manager relationship in ads.txt.
This proposal lets validators use an existing publisher-controlled signal, managerdomain, to locate authorization metadata one hop away, while preserving conservative failure behavior.
Proposal
When validating adagents.json for a publisher domain:
https://{publisher}/.well-known/adagents.jsonIf the canonical URL returns 200, process it normally. No fallback is used.
If the canonical URL returns 404, the validator MAY fetch:
https://{publisher}/ads.txtThe validator MAY parse managerdomain entries from ads.txt.
If exactly one eligible managerdomain entry remains, the validator MAY attempt:
https://{managerdomain}/.well-known/adagents.jsonIf the manager-domain file validates, the validator MAY treat it as the discovered authorization source for that publisher lookup.
If the fallback fails, the publisher should be treated as missing adagents.json, the same as if no fallback existed.
Accepted managerdomain forms
Validators SHOULD recognize both of the following forms:
MANAGERDOMAIN=example.comand the legacy/comment compatibility form:
# managerdomain=example.comKey matching SHOULD be case-insensitive. For example, all of these should be treated equivalently:
The value should be interpreted as a host token, not a URL. For example:
MANAGERDOMAIN=manager.exampleis valid, while:
MANAGERDOMAIN=https://manager.exampleshould not be treated as an eligible manager-domain value.
Safety rules
Canonical location remains primary
The canonical location remains:
https://{publisher}/.well-known/adagents.jsonThe fallback only applies when that URL returns 404.
The fallback MUST NOT replace, override, or take precedence over a valid publisher-hosted adagents.json.
Only trigger fallback on 404
Validators SHOULD only attempt the ads.txt manager-domain fallback when the publisher’s canonical adagents.json URL returns 404.
Validators SHOULD NOT use this fallback for other HTTP statuses such as 500, 403, timeout, malformed JSON, or validation failure.
One hop only
The fallback MUST be limited to one hop:
publisher -> managerdomain
Validators MUST NOT recursively follow managerdomain declarations from the manager domain’s own ads.txt.
Cycle detection
Validators SHOULD track visited domains during discovery and MUST avoid cycles.
For example, if:
the fallback should be ignored.
Ambiguity fails closed
If more than one eligible managerdomain entry remains after parsing and opt-outs, validators MUST abort fallback rather than guessing which manager to trust.
Example:
In this case, the validator should not fetch either manager domain’s adagents.json.
#noagents opt-outA managerdomain line MAY include a trailing comment containing the token noagents, case-insensitively, to exclude that manager-domain entry from adagents.json fallback discovery.
Example:
MANAGERDOMAIN=manager.example #noagentsor:
MANAGERDOMAIN=manager.example #NOAGENTSValidators MUST ignore manager-domain entries marked with #noagents.
This allows a publisher to declare a manager relationship for ads.txt purposes while explicitly preventing that entry from being used for adagents.json discovery.
No success by silence
If the manager-domain lookup fails, returns a non-200, returns invalid JSON, or does not validate as a valid adagents.json, validators MUST treat the publisher as missing adagents.json.
Fallback failure should not be interpreted as authorization.
Example
Publisher does not host adagents.json:
GET https://publisher.example/.well-known/adagents.json404 Not Found
Publisher’s ads.txt contains:
MANAGERDOMAIN=manager.exampleValidator may then attempt:
GET https://manager.example/.well-known/adagents.jsonIf that file validates, the validator may use it as the authorization source for the publisher lookup.
Non-goals
This proposal does not:
Change the canonical adagents.json location.
Require publishers to use managerdomain.
Require validators to implement fallback behavior.
Permit recursive or multi-hop discovery.
Treat ads.txt as an authorization file by itself.
Allow multiple manager domains to be tried in priority order.
Authorize agents when no valid adagents.json is found.
Compatibility
This is backwards-compatible.
Publishers already hosting /.well-known/adagents.json are unaffected.
Publishers that do not want managerdomain used for adagents.json discovery can either omit managerdomain or mark the relevant entry with #noagents.
Validators that do not implement the fallback will continue to use the canonical discovery behavior.
Suggested validator behavior
A validator implementing this RFC should:
Fetch publisher /.well-known/adagents.json.
If status is 200, validate normally.
If status is 404, fetch publisher /ads.txt.
Parse eligible managerdomain declarations.
Remove entries marked with #noagents.
Abort if more than one eligible manager domain remains.
Abort if the remaining manager domain creates a cycle.
Fetch exactly one manager-domain /.well-known/adagents.json.
Validate the manager-domain file normally.
If valid, report that the authorization source was discovered through ads.txt managerdomain.
If invalid or unavailable, fail as missing adagents.json.
Open questions
Should this behavior be described as MAY for validators, or should conforming validators be expected to implement it?
Should only IAB directive-form
MANAGERDOMAIN=example.combe accepted, or should the comment compatibility form# managerdomain=example.combe formally recognized?Should the #noagents opt-out token be standardized here, or should opt-out be handled another way?
Should a validator surface a warning when fallback succeeds, so callers know the source was manager-hosted rather than publisher-hosted?
Should the discovered manager-domain authorization file be allowed to authorize inventory for multiple publisher domains, or should additional publisher-domain scoping be required in a future revision?
Reference implementation behavior
PR #4173 implements this behavior in the ADCP validator by adding:
One-hop ads.txt managerdomain fallback on publisher adagents.json 404.
Support for both
MANAGERDOMAIN=example.comand# managerdomain=example.com.Case-insensitive key matching.
#noagents opt-out handling.
Cycle detection.
Ambiguity fail-closed behavior for multiple eligible manager domains.
Unit tests for fallback success, cycles, one-hop depth, #noagents, directive-form parsing, multiple-entry ambiguity, invalid host tokens, and non-404 behavior.