---
title: "Resolve the caller's control-plane principal, memberships, and Buzz lifecycle state"
method: GET
path: "/agent/v1/whoami"
tags: ["Org"]
---

# Resolve the caller's control-plane principal, memberships, and Buzz lifecycle state

`GET /agent/v1/whoami`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/agent/v1/whoami`
- Auth: one of:
  - API key in header `SIGN-IN-WITH-X`
  - HTTP bearer
  - HTTP bearer

SIWX, a control-plane session, or a scoped grant key bearer authenticates the caller and returns the resolved principal, active org memberships, and independent Buzz adoption/installation/enrollment eligibility and drift. A wallet and a Buzz proof are authenticators or attribution evidence, never owners by themselves. A grant key resolves to its own subject principal (typically with no memberships of its own, since a grant key acts via a project_grant rather than membership) — resolving your own identity actuates and leaks nothing beyond it, so this is grant-key-capable the same way the cold-restart-recovery `POST /projects/v1/:project_id/tokens` is.

## Headers

- `SIGN-IN-WITH-X` string, required

## Response `200`

Resolved principal + memberships

- object
  - `principal` object, nullable, required
  - `active_authenticator` ActiveAuthenticatorRepresentation, required
    - `authenticator_id` string, required
    - `kind` string, required
    - `public_subject` string, required: Only the active request authenticator's safe public subject; never an inventory or credential.
  - `linked_identities` LinkedIdentityRepresentation[], required: Current public attribution links. These do not authorize or own resources.
    - `identity_link_id` string, required
    - `proof_protocol` 'run402.identity-link.nostr.v1' | 'run402.identity-link.nostr.human.v1', required
    - `kind` string, required: Current v1 value is nostr_nip01; clients must preserve unknown future kinds.
    - `public_subject` string, required
    - `display_subject` string, required
    - `verified_at` string, date-time, required
    - `status` 'active' | 'revoked', required
    - `effective_status` 'active' | 'revoked' | 'principal_inactive', required
    - `revoked_at` string, date-time, nullable, required
  - `authenticator_id` string, nullable, required: Legacy sibling retained unchanged; equals active_authenticator.authenticator_id when present.
  - `memberships` object[], required
    - `org_id` string, uuid
    - `display_name` string, nullable
    - `role` 'owner' | 'admin' | 'developer' | 'billing' | 'viewer'
    - `status` string
  - `buzz` BuzzPrincipalStatus, required
    - `skill_installation` object, required
      - `status` 'client_managed', required
    - `capabilities` object, required
      - `human_adoption_offers` true, required
      - `browser_fragment_v1` true, required
    - `human_adoption_offers` object[], required
      - `buzz_human_adoption_offer_id` string, required
      - `org_id` string, uuid, required: A Run402 organization id, exactly as returned by GET /agent/v1/whoami, GET /orgs/v1 and GET /projects/v1. Buzz owns no organizations of its own.
      - `status` 'available' | 'completed' | 'cancelled' | 'ineligible', required
      - `offer_url` string, uri, nullable, required
    - `human_adoptions` object[], required
      - `buzz_human_adoption_id` string, required
      - `org_id` string, uuid, required: A Run402 organization id, exactly as returned by GET /agent/v1/whoami, GET /orgs/v1 and GET /projects/v1. Buzz owns no organizations of its own.
      - `status` string, required
    - `community_installations` object[], required
      - `buzz_community_installation_id` string, required
      - `org_id` string, uuid, required: A Run402 organization id, exactly as returned by GET /agent/v1/whoami, GET /orgs/v1 and GET /projects/v1. Buzz owns no organizations of its own.
      - `status` string, required
      - `default_for_enrollment` boolean, required
    - `agent_enrollments` object[], required
      - `buzz_agent_enrollment_id` string, required
      - `buzz_community_installation_id` string, required
      - `status` 'pending' | 'active' | 'denied' | 'expired' | 'cancelled' | 'revoked', required
    - `eligibility` object, required
      - `can_start_identity_link_without_organization` boolean, required
      - `can_select_community_installation` boolean, required: True only when the agent is linked and has no pending or active enrollment. The Run402 client must still discover and explicitly select a current active descriptor before requesting enrollment.
      - `has_nonterminal_enrollment` boolean, required
      - `cold_start_fallback_available` boolean, required
    - `drift` object[], required
    - `next_actions` BuzzNextAction[], required
      - `type` string, required
      - `method` 'GET' | 'POST' | 'PATCH' | 'DELETE'
      - `path` string
      - `field` string: Exact rejected request field or header when the repair is field-specific.
      - `auth` string, required
      - `why` string, required
      - `safe_to_auto_execute` boolean, required
      - `requires_approval` boolean, required
      - `destructive` boolean, required
      - `idempotent` boolean, required
      - `spend_impact` object, required
        - `currency` 'USD', required
        - `max_amount` '0', required
  - `encryption_key` object, nullable: vault-agent-envelopes D3: the principal's CURRENT vault directory key (pending or active) — metadata only, never key material. `null` = none published; the SDK's enroll-if-absent step keys off this.
    - `encryption_key_id` string, uuid
    - `ek_fingerprint` string
    - `custody_scheme` string
    - `state` 'pending' | 'active'
    - `created_at` string, date-time
    - `signing_fingerprint` string, nullable: vault-multi-writer rev 47. The principal's OPTIONAL vault-writer signing half — `vk_<32 hex>`, or `null` if never published. Never the raw `signing_pubkey`, mirroring this endpoint's existing encryption-half minimalism.
    - `signing_possession_verified_at` string, date-time, nullable: vault-multi-writer rev 47. When `signing_fingerprint`'s `possession_signature` was verified; `null` alongside a `null` `signing_fingerprint`.

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)