Accounts Protocol

​

The commercial model

​

Scope

​

Account references before provisioning

​

Account identity

• Open. A sync_accounts entry without account opens an account for a brand and an operator, and the seller returns its account_id once the account is resolved. A seller never issues an account_id it might later change, so a pending_approval row that may still resolve to a different account carries an experimental request_id instead. A retry with the same idempotency_key returns the original result. When an entry matches exactly one account in the seller’s account scope, the seller SHOULD return that account_id instead of opening another. The match follows the request_account deduplication guidance: brand and operator, with the attributes as filters and billing terms never filtering. The exact-or-reject rules for billing and payment_terms still apply. An entry whose attributes differ, such as its countries, opens a second account with its own account_id. A provisioning entry never changes an existing account. A lazy-provisioning seller opens the account on the first provisioning task instead.
• Reference. After the account opens, buyers send { "account_id": "..." }. A natural-key reference (brand + operator) resolves only when exactly one of the caller’s accounts matches it. Each supplied attribute must equal the account’s value: countries compares as a set, and operator_unit compares by id. An omitted attribute does not filter, except sandbox, which defaults to false. When several accounts match, the seller returns ACCOUNT_AMBIGUOUS and MAY list them in error.details.candidates.
• Update. brand.countries, operator_unit, currency, timezone, and sandbox are account attributes. The buyer sets them when the account opens, and a sync_accounts entry with account updates them, as it updates billing. The seller validates a changed attribute as it does when the account opens. The account_id stays the same. A seller that does not support changing an attribute rejects the entry with UNSUPPORTED_FEATURE. currency, timezone, and sandbox are set at opening: a seller MAY refuse a currency or timezone change, changing one normally means a new account, and sandbox never changes. A seller can review a countries change first, and the entry’s result then reports pending_approval while the account keeps its current countries; see Updating account attributes.

​

Account Status Lifecycle

sync_accounts ──▶ pending_approval ──▶ active
                       │                  │
                       │ (seller declines) ├── (credit limit / funds depleted)
                       ▼                  │    ▼
                   rejected (terminal)    │  payment_required
                                          │    │ (buyer resolves billing)
                                          │    ▼
                                          │  active
                                          │
                                          ├── (seller suspends) ──▶ suspended
                                          │                           │
                                          │    (seller reactivates) ◀─┤
                                          │                           │
                                          │                           └──▶ closed (terminal)
                                          │
                                          └── (seller or buyer closes) ──▶ closed (terminal)

• pending_approval → active: seller approves after credit/contract/identity review
• pending_approval → rejected: seller declines. Terminal — buyer must submit a new account request.
• active → payment_required: automatic when credit limit is reached or funds are depleted
• payment_required → active: when the buyer resolves the outstanding balance. Sellers MAY auto-transition or MAY require manual re-activation.
• active → suspended: seller-initiated (policy violation, billing dispute, fraud review). Sellers MUST notify orchestrators via webhook.
• suspended → active: seller-initiated reactivation
• suspended → closed: seller-initiated permanent closure
• active → closed: seller or buyer-initiated permanent closure. Terminal.
• Sellers MUST reject operations on accounts in terminal states with ACCOUNT_NOT_FOUND or an appropriate error

​

Operations by Account Status

• payment_required blocks new spend (create_media_buy) but allows managing existing buys and resolving setup. Sellers SHOULD also reject new_packages within update_media_buy when the account is in payment_required, since adding packages is functionally equivalent to new spend.
• suspended allows read-only access to existing data but blocks all mutations
• Sellers MUST return ACCOUNT_SUSPENDED for blocked operations on suspended accounts and ACCOUNT_PAYMENT_REQUIRED for blocked operations on payment-required accounts

​

Caller authorization

{
  "account_id": "acc_acme_compliance",
  "name": "Acme c/o AAO Compliance",
  "status": "active",
  "billing": "operator",
  "authorization": {
    "allowed_tasks": [
      "get_adcp_capabilities",
      "get_products",
      "get_media_buys",
      "get_media_buy_delivery",
      "list_creatives",
      "update_media_buy"
    ],
    "field_scopes": {
      "update_media_buy": ["reporting_webhook"]
    },
    "scope_name": "attestation_verifier",
    "read_only": false
  }
}

​

Fields

​

Semantics of presence and absence

• Present: the vendor agent asserts the shape reflects its enforcement for this caller on this account at this moment. Stale-by-seconds is fine; systematically-divergent is non-conformant.
• Absent on a single account: the vendor agent is not telling the caller their scope for that account. Caller falls back to error-driven discovery (try the task, handle the RBAC error codes).
• Absent on all accounts: the vendor agent does not implement scope introspection. Callers MUST NOT infer access from absence — the vendor agent may still enforce scope locally and return SCOPE_INSUFFICIENT / READ_ONLY_SCOPE / FIELD_NOT_PERMITTED on any task call.
• authorization is optional for 3.x. Vendor agents that want to avoid a breaking change can defer populating it. Populating is strictly additive — it lets callers preempt errors they would otherwise discover by trying.

​

Identity binding, refresh cadence, and consistency

• Callers SHOULD re-read authorization at least every 300 seconds of active use against an account, via sync_accounts or list_accounts (filtered by the held account).
• Vendor agents MUST reflect operator-initiated scope changes in sync_accounts / list_accounts responses within 300 seconds of the change being made. A compliant caller polling every 300s sees operator changes within at most one refresh cycle.
• Vendor agents MAY cache the authorization object briefly but MUST NOT cache past 300 seconds without revalidation.
• The 300s figure is a floor, not a target — vendor agents whose scope changes more frequently SHOULD surface them faster, and callers running AAO Verified (Live) attestation SHOULD probe at the check-7 cadence (at least once per rolling window, plus on every observed scope change).

​

Buyer response to SCOPE_INSUFFICIENT within the refresh window

• Retry budget: no more than 3 attempts, each separated by 1–5 seconds of jittered backoff. This is disambiguation logic — establishing whether the scope is genuinely insufficient before trusting the correctable classification — not a recovery action for a correctable error.
• Not the 300s window: the retry budget is not the seller’s propagation SLA. Buyers SHOULD NOT wait out the full 300-second window on every false negative; up to 15 seconds of accumulated backoff delay is sufficient to absorb typical replica lag.
• After retries exhaust: buyers MUST surface the error. “Surface” means: return a structured error to the calling layer (including account ID, the failed task, and error.details.retry_count with the number of attempts made) AND ensure the failure is visible in an operator-accessible channel — a structured log, dashboard alert, or notification. The escalation mechanism is implementation-defined; the requirement is that the error is not silently swallowed.

​

Standard named scope: attestation_verifier

• allowed_tasks (at minimum — vendor agents MAY include additional read-only tasks):
  • get_adcp_capabilities
  • get_products
  • get_media_buys
  • get_media_buy_delivery
  • list_creatives
  • update_media_buy
• field_scopes.update_media_buy: ["reporting_webhook"]
• read_only: false

​

Custom scopes for other vendor protocols

• Signals agent: custom:activation_only — allowed_tasks: [get_signals, activate_signal, get_adcp_capabilities], no catalog management, no cross-account metadata.
• Governance agent: custom:audit_viewer — allowed_tasks: [get_plan_audit_logs, get_adcp_capabilities], read_only: true. Useful for regulators or external auditors granted read access to governance trails.
• Creative agent: custom:library_reader — allowed_tasks: [get_adcp_capabilities, list_creatives], read_only: true. Lets a non-uploading buyer (e.g., a measurement partner) discover capabilities and library contents without mutating them.
• Measurement agent on a buyer-orchestrator gateway account: custom:measurement_feedback — allowed_tasks: [get_media_buy_delivery, provide_performance_feedback], read_only: false. These are the fixed tasks in the first experimental gateway tier. Measurement providers do not receive seller-account grants. The exact task list is normative, so no standard named scope is needed.
• Brand agent (rights): custom:rights_viewer — allowed_tasks: [get_rights, get_brand_identity], read_only: true. Discovery without clearance privilege.

​

Prior art

​

Transaction lifecycle

1. Discover seller capabilities
   get_adcp_capabilities → require_operator_auth, supported_billing

2. Resolve brand identity
   Fetch brand.domain/.well-known/brand.json → canonical brand (domain, brand_id)

3. Verify operator identity
   Check authorized_operators in brand.json → confirm operator is permitted to buy for this brand

4. Authenticate (if required)
   When require_operator_auth is true → obtain operator credential via authorization_endpoint or out-of-band

5. Establish account reference
   Account-id namespace (require_operator_auth: true):
     list_accounts() → find existing account_id for this brand/operator (upstream-managed)
     or receive account_id out-of-band (seller-defined)
   Buyer-declared account (require_operator_auth: false):
     sync_accounts({ accounts: [{ brand, operator, billing, billing_entity? }] }) → account_id, status, billing terms
     or, when all required settings are unambiguous, send the natural key on the first account-scoped task
     list_accounts() → recover account IDs after a cold start (required for lazy provisioning; otherwise SHOULD be exposed)

6. Execute
   Protocol tasks use the account reference to apply correct rates and terms
   Send { account_id }
   Examples: get_products(account: {...}), create_media_buy(account: {...})

7. Report usage
   report_usage(usage: [{ account: {...}, operator_id, kind, vendor_cost, ... }])
   Informs vendor agents how their services were consumed after delivery

​

Parties

​

Tasks

​

Brand registry connection

​

Counterparty verification

• Brand identity: Is this brand who they claim to be?
• Operator authorization: Is the operator listed in the request actually authorized to buy on this brand’s behalf?
• Brand hierarchy: Which sub-brands does this house portfolio include?

​

Brand registry and the contribute-back pattern

async function ensureBrand(domain) {
  // 1. Check registry (brand.json or previously resolved)
  const resolved = await resolveBrand(domain);

  if (resolved.errors) {
    // Resolution failed — brand unknown, proceed to enrich
  } else if (
    resolved.source === "brand_json" ||
    resolved.source === "enriched"
  ) {
    // Authoritative or enriched data available — confirm with user, then use
    return await confirmWithUser(resolved);
  }
  // source === 'community': registry has a placeholder, but enrich for richer data

  // 2. Enrich via Brandfetch — auto-saves to registry as 'enriched'
  const enriched = await researchBrand(domain);
  if (enriched.errors) {
    // Enrichment unavailable — fall back to community entry or prompt user to correct
    return resolved ? await confirmWithUser(resolved) : null;
  }

  // 3. Confirm with user before using enriched data
  // Enrichment is third-party — user confirmation catches errors and improves registry quality
  return await confirmWithUser(enriched);
}

​

Source authority

​

Property contribute-back

​

Usage reporting