Public Identity Document (PID)

The verifiable, shareable representation of an agent’s identity.

What is a PID?

A Public Identity Document (PID) is a signed JSON artifact that represents an agent’s public-facing identity. Think of it as a passport for autonomous agents—verifiable, portable, and self-contained.

┌─────────────────────────────────────────────────────────┐
│                 Public Identity Document                 │
├─────────────────────────────────────────────────────────┤
│  id: did:key:z6Mk...        (DID anchor from RIK)       │
│                                                          │
│  operationalKeys: [         (Current active OKs)        │
│    { id, publicKey, validFrom, validUntil }             │
│  ]                                                       │
│                                                          │
│  services: [                (Discovery endpoints)        │
│    { type: "AgentAPI", endpoint: "..." }                │
│  ]                                                       │
│                                                          │
│  sentinel: {                (Rotation chain metadata)    │
│    rotationTip: "...",                                   │
│    policyHash: "..."                                    │
│  }                                                       │
│                                                          │
│  proof: {                   (RIK signature)              │
│    type: "Ed25519Signature2020",                        │
│    created: "...",                                       │
│    verificationMethod: "did:key:z6Mk...#rik",           │
│    proofValue: "..."                                    │
│  }                                                       │
└─────────────────────────────────────────────────────────┘

PID Structure

Full Schema

interface PublicIdentityDocument {
  // Identity anchor (stable, derived from RIK)
  id: string;                          // did:key:z6Mk...

  // Agent metadata
  name?: string;                       // Human-readable name
  description?: string;                // Agent description
  created: string;                     // ISO 8601 timestamp
  updated: string;                     // Last modification time

  // Active operational keys
  operationalKeys: OperationalKey[];

  // Service discovery
  services: ServiceEndpoint[];

  // Rotation chain state
  sentinel: {
    rotationTip: string;               // Hash of latest rotation
    rotationCount: number;             // Total rotations
    policyHash: string;                // Hash of security policy
  };

  // Cryptographic proof (RIK signature)
  proof: Proof;
}

interface OperationalKey {
  id: string;                          // e.g., "ok-003"
  type: string;                        // "Ed25519VerificationKey2020"
  publicKeyMultibase: string;          // Multibase-encoded public key
  validFrom: string;                   // ISO 8601 start time
  validUntil?: string;                 // ISO 8601 expiry (optional)
  purposes: string[];                  // ["authentication", "signing"]
}

interface ServiceEndpoint {
  id: string;                          // Endpoint identifier
  type: string;                        // "AgentAPI", "DIDComm", etc.
  serviceEndpoint: string;             // URL
  description?: string;
}

interface Proof {
  type: string;                        // "Ed25519Signature2020"
  created: string;                     // Signature timestamp
  verificationMethod: string;          // "did:key:z6Mk...#rik"
  proofPurpose: string;                // "assertionMethod"
  proofValue: string;                  // Base64 signature
}

Example PID

{
  "id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "name": "Aura Super Assistant",
  "description": "A sovereign AI agent for VrianCao",
  "created": "2026-01-15T00:00:00Z",
  "updated": "2026-02-06T17:54:00Z",

  "operationalKeys": [
    {
      "id": "ok-003",
      "type": "Ed25519VerificationKey2020",
      "publicKeyMultibase": "z7NkoWh8vGy2aWq5nUVw1M8jRmPrHezHJK9w1cLVaxNqP",
      "validFrom": "2026-02-01T00:00:00Z",
      "validUntil": "2026-03-01T00:00:00Z",
      "purposes": ["authentication", "signing"]
    }
  ],

  "services": [
    {
      "id": "agent-api",
      "type": "AgentAPI",
      "serviceEndpoint": "https://agent.example.com/api",
      "description": "Main agent interaction endpoint"
    },
    {
      "id": "didcomm",
      "type": "DIDCommMessaging",
      "serviceEndpoint": "https://agent.example.com/didcomm"
    }
  ],

  "sentinel": {
    "rotationTip": "sha256:a1b2c3d4...",
    "rotationCount": 3,
    "policyHash": "sha256:e5f6g7h8..."
  },

  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-02-06T17:54:00Z",
    "verificationMethod": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#rik",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3Xp8Z..."
  }
}

PID Lifecycle

Creation

1. Generate RIK
       │
       ▼
2. Derive did:key from RIK
       │
       ▼
3. Generate initial OK
       │
       ▼
4. Build PID structure
       │
       ▼
5. Sign with RIK
       │
       ▼
6. Publish (web URL, content-addressed storage, etc.)

Update (Key Rotation)

1. Generate new OK
       │
       ▼
2. Update rotation chain
       │
       ▼
3. Rebuild PID with new OK list
       │
       ▼
4. Update timestamps
       │
       ▼
5. Re-sign with RIK
       │
       ▼
6. Republish

Verification

1. Fetch PID from discovery URL
       │
       ▼
2. Parse and validate structure
       │
       ▼
3. Verify proof signature against RIK
       │
       ▼
4. Check OK validity windows
       │
       ▼
5. (Optional) Verify rotation chain
       │
       ▼
6. Accept/reject identity claim

Discovery Mechanisms

Web-Based Discovery

Agent ID: did:key:z6Mk...
         │
         ▼
Well-Known URL: https://example.com/.well-known/did.json
         │
         ▼
Fetch PID

Content-Addressed Discovery

Agent ID: did:key:z6Mk...
         │
         ▼
IPFS CID or similar: ipfs://Qm...
         │
         ▼
Fetch from gateway

Direct Exchange

Agent A                          Agent B
   │                                │
   │  Request PID                   │
   │───────────────────────────────▶│
   │                                │
   │  Return signed PID             │
   │◀───────────────────────────────│
   │                                │
   │  Verify & store                │
   │                                │

Security Considerations

What’s Public

Field	Visibility	Risk
`id` (did:key)	Public	Identifier only
`operationalKeys`	Public	Needed for verification
`services`	Public	Discovery endpoints
`sentinel`	Public	Hashes, not secrets

What’s NOT in PID

Item	Reason
RIK private key	Core security asset
OK private keys	Operational secrets
RK (any form)	Recovery security
Master passphrase	Backup encryption

Verification Best Practices

Always verify proof — Never trust unsigned PIDs
Check timestamps — Reject expired OKs
Pin initial PID — Detect unauthorized changes
Monitor rotation chain — Audit key changes

W3C DID Compatibility

PID is designed to be compatible with W3C DID Core:

DID Concept	PID Implementation
DID	`id` field (did:key)
DID Document	The PID itself
Verification Method	`operationalKeys` array
Service	`services` array
Proof	`proof` object

did:key Anchoring

The did:key method derives the DID directly from the public key:

RIK Public Key (Ed25519)
         │
         │ Multibase encode
         ▼
did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

Benefits:

Offline resolution — No registry lookup needed
Cost-free — No blockchain fees
Self-certifying — DID proves key ownership

Tradeoff:

RIK rotation = DID change — Continuity via rotation chain

Key Hierarchy — RIK/OK/RK architecture
Rotation Chain — Key rotation mechanisms
DID Integration — W3C DID mapping details
Identity Sentinel — Private key storage