AdCP — get_principal

get_principal returns the authenticated caller’s seller-resolved durable identity and current principal configuration with one AdCP agent: the same caller-scoped state that sync_principal replaces, plus retained superseded and revoked destination generations. A recognized durable identity remains readable before the caller has standing configuration. The read is side-effect free. It never creates a principal record, issues identifiers, sends endpoint proof challenges, mutates state, or advances configuration_version. For the full lifecycle from credentials through destination proof and readback, see Set up your buyer agent with a seller. Request schema: /schemas/3.2.1/protocol/get-principal-request.json Response schema: /schemas/3.2.1/protocol/get-principal-response.json

When to call

Call it whenever you need current state rather than a change:

Verify identity before configuration. A recognized result exposes the seller-resolved principal_kind and existing principal_id before the first state-changing call.
Bootstrap the concurrency fence. Read configuration_version before a guarded sync_principal replacement instead of writing blind.
Recover after local-state loss. A restarted service reads principal_id, configuration_version, every destination_ref, and each destination’s setup state before deciding what to sync.
Observe setup progress. After a destination returns action_required or validating, poll here until it reaches ready — or subscribe to the principal.changed webhook and use this read as the repair path. Polling never disturbs the version fence.
Read the negotiated async contract. The declarations state carries both the declared set and the seller-computed accepted intersection that governs webhook payload versions and signing algorithms.
Audit generations. Superseded generations appear in each destination’s prior_destination_refs; revoked destinations appear in retired_destinations. Both remain resolvable for existing authorized account bindings and retained reporting history.

Only call this task when get_adcp_capabilities advertises adcp.principal with read_task: "get_principal". Sellers advertising principal implement both the sync and read tasks.

Identity

Identity resolution is identical to sync_principal: the seller resolves the stable authenticated principal from transport and ignores every request-body field for identity and authorization. The request body carries no parameters beyond the protocol envelope. For RFC 9421 signed callers, that stable identity is the canonical URL of the exactly matched operator brand.json agents[] entry after publication and key verification. Rotation to another key authorized for the same canonical Agent URL preserves the principal; a domain, JWKS URI, or key never replaces the Agent URL as the subject. For Web Bot Auth signed callers (experimental), the stable identity is the signer’s canonical origin, verified as Web Bot Auth identities describes. An identity-established caller (Web Bot Auth identities) gets unconfigured. Key rotation within the origin’s directory preserves the identity. principal_kind is resolved from authorization state, but the response exposes it only with a durable principal record: in current and recognized results. principal_id identifies that same record in both arms. A read never creates the record or mints the identifier; stable authentication without a materialized durable record returns unconfigured, which carries only kind and, when an application is in progress, relationship.

Results

`result.kind`	Meaning
`current`	The caller has standing configuration. Returns `principal_id`, the seller-resolved `principal_kind` (`buyer_agent` or `operator`), `configuration_version`, and complete credential-free configuration state.
`recognized`	The caller maps to an existing durable principal record but has no standing configuration. Returns `principal_id` and seller-resolved `principal_kind`, with no configuration or version.
`unconfigured`	Stable authentication succeeded, but the caller has no durable principal record. Carries `kind`, and `relationship` when an application is in progress.
`failed`	The read could not be served. Carries only structured errors, never identifiers or state.

The response reveals only the authenticated caller’s identity and state. It never exposes whether another principal exists or has configuration, and failed results carry no identity facts.

Relationship status

current, recognized, and unconfigured results MAY carry relationship (core/principal-relationship.json, experimental): the seller’s commercial relationship with the caller. It is marked x-added-in: 3.3.0; how a seller shapes a response for an older negotiated release is in versioning.

Field	Meaning
`status`	`enums/principal-relationship-status.json`: `pending_approval` (the seller is reviewing an application or approval, as in the account status lifecycle), `active`, `suspended`, or `blocked`. While `suspended` or `blocked`, calls that need the relationship fail with `AGENT_SUSPENDED` or `AGENT_BLOCKED`.
`expires_at`	When the relationship lapses unless renewed. Absent means no scheduled expiry.
`setup`	While `pending_approval`, the caller’s next step: `{ url, message, expires_at }`, the same shape as `sync_accounts` `setup`. Treat `url` as untrusted: surface it, never fetch it.

relationship is omitted when the seller has no relationship with the caller and no application in progress. That is the identity-established state (Web Bot Auth identities). Because the field is returned only to the authenticated caller, it is not an onboarding oracle: it says nothing about any other agent. principal.changed fires with reason relationship_changed when status changes, and with relationship_expiring at a seller-chosen lead time before expires_at. Receivers re-read get_principal. An identity-established buyer agent whose application is under review receives:

{
  "status": "completed",
  "result": {
    "kind": "unconfigured",
    "relationship": {
      "status": "pending_approval",
      "setup": {
        "url": "https://streamhaus.example/partners/applications/7k3q",
        "message": "Upload your billing entity details to finish the agent-billing application."
      }
    }
  }
}

Before configuration, a registered buyer agent with a durable principal record receives:

{
  "status": "completed",
  "result": {
    "kind": "recognized",
    "principal_kind": "buyer_agent",
    "principal_id": "prin_01K4C6RGT5Q18VCPGXE7DDWQ5F"
  }
}

An authenticated caller with no durable record receives the existing result without an invented identifier or exposed party kind:

{
  "status": "completed",
  "result": {
    "kind": "unconfigured"
  }
}

{
  "status": "completed",
  "result": {
    "kind": "current",
    "principal_id": "prin_01K4C6RGT5Q18VCPGXE7DDWQ5F",
    "principal_kind": "buyer_agent",
    "configuration_version": "cfg_01K4C6V2N5PC1TQAH9WTT8D2HP",
    "configuration": {
      "notification_configs": [],
      "reporting_destinations": [
        {
          "destination_id": "analytics-warehouse",
          "destination_ref": "dest_01K4C6T6Q0A9E6Y3N1FQ1T8YKV",
          "prior_destination_refs": ["dest_01K4C5A2M9XPZ0T4B7QCW3JHRD"],
          "state": "ready",
          "configuration": {
            "pattern": "warehouse_materialization",
            "destination_id": "analytics-warehouse",
            "active": true,
            "provider": { "domain": "data-warehouse.example" },
            "transport": "bigquery",
            "location": "pinnacle-analytics.adcp_reporting",
            "accepted_verification_profiles": ["native_commit", "canonical_digest"]
          }
        }
      ]
    }
  }
}

Seller-driven setup-state transitions observed through this task — a destination moving from validating to ready, a refreshed setup.expires_at — do not advance configuration_version. Only successful configuration mutations through sync_principal or sync_agent_notification_configs advance it.

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

get_principal

When to call

Identity

Results

Relationship status

​When to call

​Identity

​Results

​Relationship status

When to call

Identity

Results

Relationship status