> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# get_principal

> Read the authenticated caller's seller-resolved identity, principal configuration, version, and destination setup states.

`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`](/dist/docs/3.2.0-beta.10/protocol/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`](https://adcontextprotocol.org/schemas/3.2.0-beta.10/protocol/get-principal-request.json)

**Response schema:** [`/schemas/3.2.0-beta.10/protocol/get-principal-response.json`](https://adcontextprotocol.org/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`](/dist/docs/3.2.0-beta.10/protocol/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`](/dist/docs/3.2.0-beta.10/protocol/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`](/dist/docs/3.2.0-beta.10/protocol/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

| `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 only `kind`.                                                                                                         |
| `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.

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "status": "completed",
  "result": {
    "kind": "unconfigured"
  }
}
```

```json theme={null}
{
  "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`](/dist/docs/3.2.0-beta.10/protocol/sync_principal) or [`sync_agent_notification_configs`](/dist/docs/3.2.0-beta.10/protocol/sync_agent_notification_configs) advance it.