Set up operator and brand identity in chat

An account administrator can set the commercial operator domain and scope, inspect an advertiser’s linked brand, and follow supported verification work through v3. The responses include the details in text; an MCP App or Settings page is not required for these steps. Commercial identity, public branding and domain proof are separate. Saving a domain or finding a public brand.json does not grant account access, prove domain ownership or authorise an agent to act for that brand. Organisation names, login domains, users and roles are outside this setup flow.

Select the confirmed identity contract

For this workflow, send identityContract: "confirmed-v1" on every operator identity save or advertiser brand correction. Keep it on the preview, confirmation and retry calls. Replacing an existing identity in this contract requires a preview and the person’s explicit confirmation; omitting the token returns CONFLICT without saving. This contract coexists with earlier v3 saves on the same tools. Calls using only the earlier fields retain their existing behaviour, including one-call Buyer operator and advertiser brand updates and the Seller’s confirmOperatorDomainProfileReset check. They do not acquire a new preview requirement. New setup integrations should select confirmed-v1 explicitly. Supplying preview (including false), confirmationToken, or an advertiser update’s publicBrand also opts into the confirmed contract. An unsupported identityContract value is rejected; it does not fall back to an earlier save.

Find the account and its current identity

Call tools/list, then get_status. Use switch_account with an account ID returned by get_status if you need a different account, and read status again. A principal with several accounts must select the Buyer or Seller Account it intends to configure. An Organisation-only account provides orientation and support asks; it does not expose a separate identity editor.

Active account	Read	What to inspect
Buyer	`get_status`	`operatorIdentity`: domain, source, scope, unit, lock, domain proof and AAO evidence
Seller	`get({ "kind": "seller", "include": ["identity"] })`	Operator domain, verification, saved branding and the current human review
Buyer advertiser	`get({ "kind": "advertiser", "id": "ADVERTISER_ID" })`	`brandIdentity`: BrandRef, saved name, logo, manifest URL and provenance

For a Buyer, operatorDomainSource: "legacy_customer_domain" identifies a fallback from the account record. It is not a confirmation of commercial scope. domainProof reports the separately recorded verification and its source. organization and aao describe the evidence used by readiness; inspect them alongside scopeStatus and locked. For an advertiser, source: "saved_brand_link" means a saved branding snapshot. It does not assert that a published document is available now. A Seller’s identity.source: "storefront_config" likewise describes saved configuration. manifestUrl: null means that this read cannot identify a published URL.

Confirm the Buyer’s operator

Use save_buyer_operator as an account administrator:

{
  "identityContract": "confirmed-v1",
  "operatorDomain": "agency.example",
  "operatorScope": "whole_operator"
}

For one office, team, region or seat, use operatorScope: "specific_unit" and a stable operatorUnitId. Do not invent a unit called default. Before replacing an existing domain or confirmed scope, send the proposed values with preview: true. This explicitly requests action: "preview" without saving. Show the person the before and after values and any loss of domain proof. After they confirm, repeat the same request without preview and with the returned preview.confirmationToken. In confirmed-v1, an unconfirmed replacement that does not request a preview returns isError: true with code: "CONFLICT" and saves nothing. A successful preview is returned only when you explicitly request one. A caller that attempts an unconfirmed replacement in this contract receives an error rather than a successful-looking result that preserves the old identity. The confirmation belongs to that account, current identity and requested change. A stale or different confirmation fails with CONFLICT; read and preview again. An identical retry with no new proof returns unchanged, preserves confirmation timestamps and domain proof, and does not create a second identity audit event. A successful write returns a resource receipt and its audit ID. Read get_status again to check the persisted domain, scope and proof. The first advertiser binding locks the operator identity. A locked correction requires support, rather than a different domain spelling or another account.

Resolve and link public branding

In a Buyer Account, call save_advertiser with only:

{ "resolveBrand": "brand.example" }

In a Seller Account, the same lookup is available through save_seller with only resolveBrand. Both lookups are read-only. They require a published brand.json or an AAO-hosted brand identity and do not fall back to inferred branding. Inspect resolved, identity.brandRef, identity.source, name, logo and manifestUrl. An unavailable registry returns an error; a missing brand returns resolved: false and may supply a builder link. To create a Buyer advertiser that requires public branding, call save_advertiser:

{
  "name": "Example brand",
  "brand": "brand.example",
  "publicBrand": true,
  "idempotencyKey": "example-brand-setup-1"
}

This create operation does not accept identityContract; use that field only when correcting the brand of an existing advertiser. Keep the key and creation fields unchanged when retrying. A key reused for a different request is rejected. The creation receipt includes its audit event ID. Existing calls that omit publicBrand retain the normal brand-resolution behaviour, which may include inferred branding. To correct an advertiser’s brand, supply identityContract: "confirmed-v1", advertiserId, brand, preview: true, and optionally publicBrand: true. An account administrator must review the returned preview and repeat the request without preview and with its top-level confirmationToken after the person confirms. An unconfirmed replacement in this contract without preview: true returns CONFLICT and saves nothing. A saved replacement returns advertiser.identityChangeReceipt with its audit ID and brand-link IDs. Read the advertiser again to verify brandIdentity. The first campaign or seller-account binding locks advertiser identity. If brandIdentity is null, the saved link cannot be inspected safely. Request support with save_ask to repair that legacy record before replacing it. An identical brand-only retry does not rewrite the link. With publicBrand: true, it also checks that public identity is currently available and returns that lookup separately from the saved snapshot. It does not refresh the saved name, logo or document contents.

v3 can resolve public branding and link an advertiser to a resolved brand. It cannot create, edit or publish brand.json, choose who owns an AAO-hosted document, or refresh a saved snapshot in place. Use the domain publisher or the returned external builder for document changes. These responses report editingSupported: false. A public lookup is never domain proof.

Confirm the Seller’s operator and follow proof

Use save_seller as an account administrator:

{
  "identityContract": "confirmed-v1",
  "operatorDomain": "seller.example"
}

For a replacement, include preview: true before any fields change. Review the previous domain, proof and profile values, then repeat without preview and with its top-level confirmationToken after the person confirms. An unconfirmed replacement in this contract without preview: true returns CONFLICT and saves nothing. Fields curated for the previous domain, including description, channels, membership status and website, may be cleared. Description and channels can be supplied in the same request to replace those values; the other legacy profile fields are not writable in v3. An intervening identity or profile change requires a fresh preview. The older confirmOperatorDomainProfileReset flag alone does not replace a confirmation token in confirmed-v1; its earlier behaviour remains available to existing callers as described above. The save returns a receipt with its audit ID and, when present, the domain review ID. Saving the domain uses the existing verification service and human review queue. An already approved domain may verify immediately; otherwise the current review is visible through:

{ "kind": "seller", "include": ["identity"] }

Inspect operatorDomainVerified and identity.domainProof.review. The review contains its ID, domain, status, request time, revision, decision time and ETA when assigned. Poll this same read after the human responds. PENDING is not proof; REJECTED requires a correction or support follow-up. Verification is complete when the persisted domain matches the intended domain and operatorDomainVerified is true. A repeated identical save does not duplicate the review. Saving a Seller domain does not copy the public lookup’s logo or other document fields into Seller configuration. A domain-only save for the already saved domain returns unchanged; members can make that request without administrator write permission or a proof-review read. Actual domain changes require an administrator. Proof reads are cancellable and have a bounded wait. If a transient read failure returns SERVICE_UNAVAILABLE, retry get.

Request a person when proof or correction needs help

Show the person the proposed support request before filing save_ask:

{
  "type": "support",
  "title": "Verify our commercial operator domain",
  "detail": "Our saved operator is agency.example. We need help completing domain proof. Please provide the verification steps."
}

Keep the returned askId. In a Buyer or Seller Account, poll it with get({ "kind": "ask", "id": "ASK_ID" }), follow the human’s instructions, then re-read identity. A filed or resolved ask does not itself verify a domain. Do not paste passwords, OAuth tokens or other secrets into chat. If support approves a Buyer domain, repeat save_buyer_operator with the saved domain and scope to record that approval, then check get_status again. The save checks approved evidence separately; repeating domain text without that evidence cannot verify it. Buyer AAO OAuth verification currently has no portable v3 initiation or callback flow. v3 can inspect its evidence and request human help, but cannot complete that OAuth proof in a text-only host. A Seller review with no current record, a rejected review, or a locked identity correction can use the same support path. Shared workflows covers ask states and follow-up.

Start building

Build your integration

Workflow recipes

MCP reference

Shared reference

Set up operator and brand identity in chat

Select the confirmed identity contract

Find the account and its current identity

Confirm the Buyer’s operator

Resolve and link public branding

Confirm the Seller’s operator and follow proof

Request a person when proof or correction needs help

​Select the confirmed identity contract

​Find the account and its current identity

​Confirm the Buyer’s operator

​Resolve and link public branding

​Confirm the Seller’s operator and follow proof

​Request a person when proof or correction needs help

Select the confirmed identity contract

Find the account and its current identity

Confirm the Buyer’s operator

Resolve and link public branding

Confirm the Seller’s operator and follow proof

Request a person when proof or correction needs help