Skip to main content
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. Request schema: /schemas/3.2.0-beta.10/protocol/get-principal-request.json Response schema: /schemas/3.2.0-beta.10/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. 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 remains the exact kind-only unconfigured result.

​
Results

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. Before configuration, a registered buyer agent with a durable principal record receives:
An authenticated caller with no durable record receives the existing result without an invented identifier or exposed party kind:
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.