Buyer & Agent Management¶

This guide covers two key operator tasks: managing API keys for buyer authentication and managing agent trust for agent-to-agent interactions.

API Key Management¶

API keys have a role:

All /auth/api-keys* routes require an existing operator credential. Bootstrap the first operator key with the CLI (no HTTP auth):

ad-seller create-operator-key --label "Primary operator"

List and revoke the same way:

ad-seller list-operator-keys
ad-seller delete-operator-key --label "Primary operator"
# or: ad-seller delete-operator-key --key-id key-a1b2c3d4

See Authentication for the full operator surface.

Create a Buyer API Key¶

curl -X POST http://localhost:8000/auth/api-keys \
  -H "Authorization: Bearer <operator_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "seat_id": "seat-mediamath-001",
    "seat_name": "MediaMath",
    "dsp_platform": "MediaMath",
    "agency_id": "agency-groupm-001",
    "agency_name": "GroupM",
    "agency_holding_company": "WPP",
    "advertiser_id": "adv-cocacola-001",
    "advertiser_name": "Coca-Cola",
    "label": "GroupM - Coca-Cola Q1 2026",
    "expires_in_days": 90
  }'

Response:

{
  "key_id": "key-abc12345",
  "api_key": "ask_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "identity": {
    "seat_id": "seat-mediamath-001",
    "agency_id": "agency-groupm-001",
    "advertiser_id": "adv-cocacola-001"
  },
  "role": "buyer",
  "label": "GroupM - Coca-Cola Q1 2026",
  "expires_at": "2026-06-08T12:00:00Z"
}

Create an Operator API Key¶

curl -X POST http://localhost:8000/auth/api-keys/operator \
  -H "Authorization: Bearer <operator_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Ops secondary key",
    "expires_in_days": 365
  }'

Operator keys have no buyer identity fields — only label and optional expires_in_days.

Available Fields (Buyer Keys)¶

The identity fields determine the buyer's access tier:

• Only seat_id -> SEAT tier
• seat_id + agency_id -> AGENCY tier
• seat_id + agency_id + advertiser_id -> ADVERTISER tier
• No identity fields -> PUBLIC tier

List API Keys¶

curl http://localhost:8000/auth/api-keys \
  -H "Authorization: Bearer <operator_api_key>"

Response (metadata only, no secrets):

{
  "keys": [
    {
      "key_id": "key-abc12345",
      "role": "buyer",
      "label": "GroupM - Coca-Cola Q1 2026",
      "created_at": "2026-03-10T12:00:00Z",
      "expires_at": "2026-06-08T12:00:00Z",
      "is_active": true
    }
  ],
  "total": 1
}

Get Key Details¶

curl http://localhost:8000/auth/api-keys/{key_id} \
  -H "Authorization: Bearer <operator_api_key>"

Revoke an API Key¶

curl -X DELETE http://localhost:8000/auth/api-keys/{key_id} \
  -H "Authorization: Bearer <operator_api_key>"

Response:

{
  "key_id": "key-abc12345",
  "status": "revoked"
}

Revoked keys return 401 Unauthorized when used.

Configuration¶

Agent Trust Management¶

When buyer agents interact with the seller via A2A protocols, the seller agent maintains a local registry of known agents with trust levels that control access tiers.

Agent Discovery¶

The seller agent exposes its identity at the standard A2A well-known endpoint:

curl http://localhost:8000/.well-known/agent.json

This returns the seller's agent card with capabilities, supported protocols, and inventory types.

Discover a Buyer Agent¶

To onboard a new buyer agent, discover it by URL:

curl -X POST http://localhost:8000/registry/agents/discover \
  -H "Authorization: Bearer <operator_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_url": "https://buyer-agent.example.com"
  }'

This performs:

1. Fetches the buyer's agent card from https://buyer-agent.example.com/.well-known/agent.json
2. Checks all configured registries (AAMP primary + any extras) for verification
3. Registers the agent locally with appropriate trust status
4. Returns the agent record and maximum access tier

Response:

{
  "agent": {
    "agent_id": "agent-abc12345",
    "agent_card": {
      "name": "MediaBuy Agent",
      "url": "https://buyer-agent.example.com",
      "description": "Automated media buying agent",
      "version": "1.0.0"
    },
    "agent_type": "buyer",
    "trust_status": "registered",
    "registry_sources": [
      {
        "registry_id": "aamp-iab",
        "registry_name": "IAB Tech Lab AAMP",
        "verified_at": "2026-03-10T12:00:00Z"
      }
    ]
  },
  "max_access_tier": "seat",
  "is_blocked": false
}

Trust Status Levels¶

List Registered Agents¶

# All agents
curl http://localhost:8000/registry/agents

# Filter by type
curl "http://localhost:8000/registry/agents?agent_type=buyer"

# Filter by trust status
curl "http://localhost:8000/registry/agents?trust_status=registered"

Update Agent Trust¶

Promote an agent from unknown to approved:

curl -X PUT http://localhost:8000/registry/agents/{agent_id}/trust \
  -H "Authorization: Bearer <operator_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "trust_status": "approved",
    "notes": "Verified identity, approved for full access"
  }'

Response:

{
  "agent_id": "agent-abc12345",
  "trust_status": "approved",
  "max_access_tier": "advertiser",
  "notes": "Verified identity, approved for full access"
}

Block an Agent¶

curl -X PUT http://localhost:8000/registry/agents/{agent_id}/trust \
  -H "Authorization: Bearer <operator_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "trust_status": "blocked",
    "notes": "Suspicious behavior detected"
  }'

Blocked agents receive 403 Forbidden on all requests.

Remove an Agent¶

curl -X DELETE http://localhost:8000/registry/agents/{agent_id} \
  -H "Authorization: Bearer <operator_api_key>"

Response:

{
  "agent_id": "agent-abc12345",
  "status": "removed"
}

Onboarding Workflow¶

Here is the complete workflow for onboarding a new buyer agent:

sequenceDiagram
    participant Buyer as Buyer Agent
    participant Seller as Seller Agent
    participant Registry as AAMP Registry
    participant Op as Publisher Operator

    Buyer->>Seller: GET /.well-known/agent.json
    Note right of Buyer: Discovers seller capabilities

    Op->>Seller: POST /registry/agents/discover
    Note right of Op: Operator credential required
    Seller->>Buyer: GET /.well-known/agent.json
    Seller->>Registry: Verify agent registration
    Registry-->>Seller: Registered / Not found
    Seller-->>Op: Agent record + trust status

    Note over Op: Agent starts as "unknown" or "registered"

    Op->>Seller: PUT /registry/agents/{id}/trust
    Note right of Op: {"trust_status": "approved"} (operator auth)

    Op->>Seller: POST /auth/api-keys
    Note right of Op: Create buyer key with identity (operator auth)

    Op-->>Buyer: Share buyer API key securely

    Buyer->>Seller: POST /proposals (with buyer API key)
    Note right of Buyer: Full access at approved tier

Step-by-Step¶

1. Buyer discovers seller -- The buyer agent fetches GET /.well-known/agent.json from the seller to learn about capabilities and supported protocols.

2. Operator discovers buyer -- The publisher operator calls POST /registry/agents/discover (operator credential required) with the buyer agent's URL. The seller fetches the buyer's agent card and checks external registries.

3. Agent is registered locally -- The agent starts as unknown (PUBLIC access) or registered (SEAT access) depending on whether it was found in an external registry.

4. Operator reviews and upgrades trust -- After due diligence, the operator calls PUT /registry/agents/{id}/trust to upgrade the agent to approved or preferred.

5. Operator creates a buyer API key -- The operator creates a buyer key with the buyer's identity (seat, agency, advertiser) via POST /auth/api-keys. (Operator keys use POST /auth/api-keys/operator or ad-seller create-operator-key for bootstrap.)

6. Key is shared securely -- The operator shares the buyer API key with the buyer through a secure channel.

7. Buyer transacts -- The buyer agent uses the API key for all subsequent requests, receiving pricing and access appropriate to their tier.

Configuration¶

Multi-Registry Support¶

The seller agent can check multiple registries. Each registry gets a unique registry_id derived from its URL. Configure additional registries:

AGENT_REGISTRY_URL=https://tools.iabtechlab.com/agent-registry
AGENT_REGISTRY_EXTRA_URLS=https://registry.adtech-consortium.com,https://internal-registry.publisher.com

When an agent is discovered, all configured registries are checked. If the agent is found in any registry, it receives registered trust status.

Current Limitations¶