> ## 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.

# Which domain is which

> Your account's registered domain, your brand domain, and your publisher domains do different jobs, and only one of them is the inventory you sell. How each is verified and what to do when verification stays pending.

Three different domains describe a seller. A small publisher has one domain doing
all three jobs, so they are easy to confuse. When they differ, for example after a
rebrand, for a holding company, or for a network that sells other people's sites,
the difference decides whether a storefront can go live.

| Domain | What it answers | Where it lives |
| - | - | - |
| **Registered domain** | Which account is this, and do we know you own it? | On your account, normally taken from the email you signed up with |
| **Brand domain** | Who is selling, commercially? | The seller's `operatorDomain`. Read it with `get({ "kind": "seller", "include": ["identity"] })`, set it with `save_seller`. |
| **Publisher domain** | What inventory is being sold? | The domains in your publisher coverage. Each domain's `adagents.json` says who may sell it. |

Only the third is inventory. A brand domain is never a product's coverage. See
[Publisher coverage](https://docs.apostra.com/v3/seller-publisher-coverage.md) for publisher domains and
[Identity documents](https://docs.apostra.com/v3/identity-documents.md) for `adagents.json` and `brand.json`.

## Choose a domain for Public distribution

Your public listing domain is the address where Apostra hosts your public listing.
Use a subdomain that does not serve anything today, such as `ads.example.com`.
Do not use the domain where your website runs, such as `example.com` or
`www.example.com`: pointing it at Apostra would send website visitors to your
public listing instead. Most DNS providers also do not allow the required CNAME
on a bare domain such as `example.com`.

1. In **Public distribution**, enter the address only, such as `ads.example.com`,
   without `https://` or a path.
2. At your DNS provider, add the CNAME and TXT ownership records Apostra shows
   you. The CNAME must point to Apostra's displayed target.
3. After the DNS records have updated, select **Check my domain**. The check
   passes once Apostra can read the TXT record and follow the CNAME to its target.

For example, if your website is `www.example.com`, use `ads.example.com`. Your
listing will be served at `https://ads.example.com/`, with its JSON at
`https://ads.example.com/card.json` and its embed at
`https://ads.example.com/embed`.

### With the API

An account administrator can do the same steps with `save_seller`, one
`distribution` change per call. Each call answers with the updated Distribution
read, which you can also read with `get({ "kind": "distribution" })`.

1. Send `{ "distribution": { "hostname": "ads.example.com" } }`. The answer shows
   the CNAME and TXT records to add.
2. After the DNS records have updated, send
   `{ "distribution": { "activateHostname": true } }`. A check that finds a
   problem answers with the status it observed. It is not an error, so read the
   answer, fix the record and send it again.

To replace a saved domain, send the new `hostname` with `"preview": true` first.
The preview writes nothing and returns a `confirmationToken`. Replacing the
domain takes your public listing offline until the new one verifies, so show the
change to the person, then send the same `hostname` with that
`confirmationToken`.

To take your listing off Apostra and the public web, send
`{ "distribution": { "visibility": "unlisted" } }`. That takes effect at once.

To list it on Apostra, send `{ "distribution": { "visibility": "interchange" } }`.
To list it on the public web, send `{ "distribution": { "visibility": "public" } }`,
which needs a verified public listing domain. Listing puts your listing in front
of buyers or the open web under your brand, so neither takes effect when you
send it. `save_seller` records the request and answers `approval_required` with
a link. An administrator of the account approves it on our site, and the listing
changes only then. While the approval waits, repeating the same call returns the
same link. Once it is approved, the same call answers with the updated
Distribution read. If the approval is rejected, expires or fails, nothing is kept
of it, so a repeated call starts a new approval; read `get` with
`kind: "distribution"` to see the current visibility first.

### What the ChatGPT reviewer sandbox is

OpenAI's reviewers need a login to try your storefront before the ChatGPT app is
approved. The reviewer sandbox is that login. It gives a reviewer a view of your
storefront as a buyer sees it, and nothing more:

* **It cannot spend money.** Requesting the sandbox creates one System advertiser
  inside your account, marked as a sandbox advertiser. A sandbox advertiser is
  permanently no-spend: it has no real billing, so nothing a reviewer does can
  buy media or charge your account.
* **It is read-only.** The login carries read permission only, for that one
  advertiser. A reviewer can read what the buyer tools show, but cannot create or
  change a campaign, a media buy, a creative or any of your settings, and
  cannot see your other advertisers or any of their data.
* **It does not change your listing.** Revoking or expiring the sandbox removes
  the login and deactivates the System advertiser. It never touches
  your storefront, your listing or your brand.
* **It is short-lived and yours to revoke.** A sandbox is granted for 90 days at
  a time, and you can revoke it now with `save_seller`. Reviewers sign in with a
  generated email and password that only an administrator of your account can
  open, on our site. No tool returns that login.

Requesting a sandbox needs a public listing, and an account can request one three
times in a rolling 24 hours. Because the sandbox gives people outside your
company a login, it takes effect only after an administrator of your account
approves it on our site; see [Distribution writes](https://docs.apostra.com/v3/tool-reference.md#distribution-writes-with-save_seller).

### Give your storefront agent a text number

The Distribution read shows the storefront agent's text line when the account has
the text channel. Buying the line costs money: Apostra buys one US local SMS
number in the area code you choose, and the carrier charges an upfront fee and a
monthly fee. So `save_seller` does not buy it on the call. Send
`{ "distribution": { "requestTextLine": { "areaCode": "347", "requestId": "<a new UUID>" } } }`
and it records the request and answers `approval_required` with a link. An
administrator of the account approves it on our site, and the number is requested
only then. The approval page shows the area code and the most the carrier may
charge upfront and each month. The order is refused if the carrier's quote is
above those limits.

While the approval waits, sending the same `requestId` returns the same approval.
Once the line shows that request, the same call answers with the updated
Distribution read and there is nothing left to approve. If the approval is
rejected, expires or fails, nothing is bought, so send the same `requestId` again
to start a new approval. The call is refused up front when the account has no
text channel, has no storefront yet, or its agent already has a line or a request
in progress, so an administrator is never asked to approve something that cannot
go ahead.

### Read your ChatGPT app setup and download links

The Listing page and your agent read your ChatGPT app and its files with the same
call. A seller account administrator can ask for either part of
`get({ "kind": "distribution" })` with `include`:

* `include: ["chatgpt"]` returns `object.chatgpt`: your listing as the ChatGPT app
  will show it (name, subtitle, description, URLs and category), the icon mode,
  whether you have approved this exact listing, the readiness of the submission
  package, the status of the reviewer sandbox, and `reviewerLoginUrl`, a link to
  the web page that shows the reviewer login. It never returns the login itself.
  Your name, subtitle and description are text you wrote, so a
  reply a model reads wraps them as untrusted. Your first read creates the empty
  ChatGPT registration for the account.
* `include: ["files"]` returns `object.files`: a `downloadUrl` for the OpenAI
  submission package and one for the printable listing card PDF. Each link is
  signed when you ask, works for two minutes and opens only that file, so read
  again for a fresh one. A file with no link says why: the package needs a live
  address, reviewer access, proof of domain ownership and your approval of the
  current listing, and the card needs a published listing.

In the `chatgpt` part, `submissionReadiness` says whether the package can be
downloaded: `ready`, the `missing` prerequisites in the order you meet them
(`public_live`, `reviewer_access`, `domain_proof`, `package`), and
`blockedReason`, one plain line naming the first one still outstanding.
`bundleAvailable` only says the package can be built, and the download itself
refuses with the same reason until it is ready. `reviewerSandboxAvailable` is
`true` only while Public distribution and the full entitlement bundle permit a
new reviewer request. `reviewerSandboxGrantStatus` is `loaded` when both the
eligibility and the grant lookup succeeded, and `unavailable` when either one
fails, so a caller retries instead of treating an outage as a missing
entitlement. An existing grant stays visible and revocable if a later change
makes a new request ineligible.

### See the reviewer login

The reviewer login is the email and password that OpenAI's reviewers use to sign
in to your reviewer sandbox. It is a secret, so no tool returns it and the Listing
page never shows it. Instead, `object.chatgpt.reviewerLoginUrl` is a link to a
page in the web app while the reviewer sandbox is active, and `null` otherwise.
The Listing page's **Open reviewer login** button opens the same link.

Open the link in your own browser, signed in to the web app as an administrator of
the seller account itself, and choose **Show the login**. The page shows the email,
the password and when reviewer access ends, with a button to copy them. It reads
nothing until you choose to show it, and it never keeps the login: leaving the
page drops it.

Only a person can see it. An agent, an API key, a service token and an
administrator who reaches the account through a parent organization are all
refused, and so is a member who is not an administrator. The page also refuses
when there is no active reviewer access: request it first with the Listing page's
**Request access** button. Every time the login is shown, the audit log records
who saw it. The login stops working when reviewer access ends or is revoked. The
login can only read your sandbox advertiser and cannot spend.

The default read, `get({ "kind": "distribution" })`, stays a short summary. The
printable card is built from your published listing when the link is opened, so a
listing the card cannot print, for example one with overlong text, shows its
error in the browser.

An organization also claims the domain it operates as, and its buyer accounts take
that claim as their operator domain. Open the organization's Domains page with
`open_domains_page`; [Your organization's domain](https://docs.apostra.com/v2/buyer/account/tasks/organization-domains.md)
has the steps.

Every domain is held at the organization, so a buyer or agents account in an
organization does not type a registered domain of its own. It picks one of the
organization's verified domains, or none, in **Settings → Account configuration**,
and takes the organization's proof with it. A domain an account already holds
stays until it is cleared or replaced. A seller account keeps its own brand domain
until the organization's claims take it over in a later step.

### A worked example

Raptive runs a network and sells CafeMedia's sites.

* **Registered domain** `raptive.com`: the account was created by someone with a
  `@raptive.com` email.
* **Brand domain** `raptive.com`: Raptive is who the buyer deals with.
* **Publisher domains** `cafemedia.com`, `wholesomeyum.com` and others: the sites
  whose inventory is for sale, each with its own `adagents.json`.

Here the registered and brand domains match. That is the easy case, and it
verifies automatically. The rest of this page covers what happens when they do not.

## Why the brand domain must be verified

The brand domain is the seller's buyer-facing identity. Apostra reads the logo and
company description from it, and it is what a buyer sees they are dealing with, so
Apostra does not take it on assertion. An unverified brand domain blocks go-live. It
shows as the `operator_domain` check in the seller's
[setup checklist](https://docs.apostra.com/v3/seller-readiness.md) and stays a blocker until it resolves.

Verification depends on whether the brand domain matches the account's registered
domain.

### The brand domain matches the registered domain

The registered domain must be **approved**. An account administrator, or an
administrator of the organization that manages the account, can get there three
ways, for buyer, seller and organization accounts alike:

1. **An email on the domain.** An active member of the account has an email address
   at the registered domain. This needs nothing beyond signing in with that address.
2. **A DNS TXT record.** In your account's domain settings in the Apostra web app,
   choose **Verify with a DNS record**. Apostra shows a record name and value. Add
   that TXT record at your DNS provider, then choose **Check now**. Apostra reads
   the record straight from DNS, with no third party and no sign-in.
3. **A manual review.** Choose **Request manual review** and say why the first two
   do not fit, for example because you are an agency working for a client. An
   Apostra administrator reviews it and, if it holds up, attests the domain.

Starting a DNS check or a review happens in the web app's domain settings, not in a
V3 tool. Once the registered domain is approved, a brand domain equal to it
verifies automatically and the checklist updates right away, with no sync to wait
for.

#### The DNS record

The record sits at a dedicated host under your registered domain, so it does not
add to the TXT records at the domain's apex:

| Part | Value |
| - | - |
| Name | `_apostra-domain-verification.<your registered domain>` |
| Value | `apostra-domain-verification=<token>` |

The token is random and belongs to one account and one registered domain. If you
change the account's registered domain, Apostra issues a new token for the new
domain, and the old record does not verify it. Some DNS providers add the domain
for you, so enter the name as `_apostra-domain-verification` if yours does.

DNS changes can take a few minutes to appear. Until Apostra sees the exact value,
the check stays pending, whether the record is missing, wrong, or the lookup did
not finish. A check never approves a domain on a failed lookup. One account can run
a check about once every five seconds; a check made sooner is refused with
`RATE_LIMITED`. If the domain is already approved, for example by an email on the
domain, there is nothing to verify.

> [!NOTE]
>
> Verify via AAO is no longer offered. Its routes answer `410 Gone` and point to the
> DNS record and manual review. An approval made earlier through it stays valid.

If verification stays pending here, the account domain has not been approved yet.
That is what to chase, not the brand domain.

### The brand domain differs from the registered domain

This is the case that generates support requests. A seller registers as
`spanglishmovies.com` and sells as `latinxctv.com`. A company owns both `loopme.ai`
and `loopme.com`. Both are legitimate, and neither verifies on assertion. Two
conditions must hold, in order:

1. **The registered account domain is approved**, as above. Alias evidence is never a
   way around this. An unapproved account cannot verify any brand domain.
2. **Published evidence links the two domains.** Apostra reads each domain's
   `brand.json` through the AgenticAdvertising.org (AAO) registry and looks for one
   domain naming the other. It counts when either domain's `brand.json` lists the
   other in `authorized_operators`, names it as its `authoritative_location` or
   `house`, or lists it as one of its website properties.

> [!WARNING]
>
> A website redirect is not ownership proof. Pointing `old.com` at `new.com`, or
> serving the same site from both, verifies nothing. The evidence has to be a
> published claim in a `brand.json`, not server behavior.

A DNS record, an email address or a review for your registered domain does not prove
a different brand domain. Only the published link does.

Apostra cannot yet tell "no link is published" from "the lookup did not finish". Either
way the check stays pending, and the checklist says Apostra could not complete the
evidence check. If you have not published the link, publish or correct it in
`brand.json` at both domains. That is yours to do, because Apostra reads what you
publish. If you have published it and the check is still pending, it is waiting on
Apostra, and you can file that with `save_ask` rather than waiting.

## Change a brand domain

Saving a new brand domain with `save_seller` runs verification against it from
scratch, so expect the `operator_domain` check to go back to pending until the new
domain resolves. [Identity and brands](https://docs.apostra.com/v3/identity-setup.md#confirm-the-sellers-operator-and-follow-proof)
shows the preview and confirmation that a change needs.

* **Saving the same brand domain again re-runs nothing.** A brand domain that is
  already verified, including one an Apostra administrator attested, keeps its
  verification when you update other parts of the profile.
* **A lookup that fails counts as "not verified".** If the registry or `brand.json`
  lookup times out, the result is never "verified". A pending check after a change may
  only mean the lookup has not completed. The check runs again each time the
  storefront is read, so read it again to retry.
* **Withdrawing approval withdraws the verification.** If the account domain stops
  being approved, a brand domain that was verified through that approval goes back to
  pending. A verification an Apostra administrator attested directly stays.

## When it stays pending

Work down this list. Each step has a different owner.

1. **Is the account's registered domain approved?** Nothing else can succeed first.
   It needs a member email on the domain, a DNS TXT record Apostra has checked, or
   Apostra's attestation. The checklist says which can work for you. If no active
   member of the organization has an email address on the registered domain, email
   cannot work, so use the DNS TXT record or **Request manual review**. This is common
   when a company's people email from one domain and its brand lives on another.
2. **Does the brand domain match the registered domain?** If it does and it is still
   pending, the blocker is step 1.
3. **If it differs, is the linking evidence published?** Check that one domain's
   `brand.json` names the other. Redirects do not count.
4. **Evidence published and still pending?** It is with Apostra for review. File a
   request with `save_ask`.

## Related

* [Identity documents](https://docs.apostra.com/v3/identity-documents.md) explains `adagents.json`, `brand.json`
  and the AAO registry.
* [Identity and brands](https://docs.apostra.com/v3/identity-setup.md) covers setting and proving a domain in chat.
* [Publisher coverage](https://docs.apostra.com/v3/seller-publisher-coverage.md) covers publisher domains and
  properties.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.