🆔 Agent Identity¶

Give your agent a verifiable identity in under 60 seconds — just like Let's Encrypt did for HTTPS.

The Problem¶

AI agents today have an identity crisis:

• API keys prove you paid, not who you are
• OAuth tokens expire and require constant refresh
• Hostnames change when you move providers
• Self-descriptions can be forged by anyone

Result: No way to know if you're talking to the agent you think you're talking to.

The Solution: One Command Setup¶

CapiscIO gives every agent a DID — a globally unique, cryptographically verifiable identifier:

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
└───────────────────────────────────────────────────────────┘
              Your agent's permanent identity

Get it with one command:

export CAPISCIO_API_KEY=sk_live_...
capiscio init

from capiscio_sdk import CapiscIO

# Simplest: reads CAPISCIO_API_KEY from environment
agent = CapiscIO.connect()
print(agent.did)  # did:key:z6Mk...

# Or pass explicitly
agent = CapiscIO.connect(api_key="sk_live_...")

# connect() reads these automatically:
export CAPISCIO_API_KEY=sk_live_...       # Required
export CAPISCIO_AGENT_ID=my-agent         # Optional
export CAPISCIO_SERVER_URL=https://...    # Optional (defaults to production)

agent = CapiscIO.connect()  # Reads from env vars

This identity:

• ✅ Proves identity — Cryptographically signed, unforgeable
• ✅ Stays with you — Move providers, keep your identity
• ✅ Works everywhere — W3C standard, interoperable
• ✅ Scales trust — Link to organizational verification

Full setup instructions

What You Get¶

After running capiscio init, your .capiscio/ directory contains:

.capiscio/
├── private.jwk      # Ed25519 private key (0600 permissions - keep secret!)
├── public.jwk       # Public key for verification
├── did.txt          # Your agent's did:key identifier
└── agent-card.json  # A2A-compliant agent card with x-capiscio extension

How DIDs Work¶

sequenceDiagram
    participant A as Your Agent
    participant R as CapiscIO Registry
    participant B as Other Agent

    Note over A: capiscio init generates keypair
    A->>R: Register DID + public key
    R-->>A: ✅ Identity registered

    Note over A,B: Later, when communicating...
    A->>B: Request + JWS signature
    B->>R: Resolve DID → get public key
    R-->>B: DID Document with public key
    B->>B: Verify signature
    Note over B: ✅ Confirmed: really "you"

The DID Document¶

When someone resolves your DID, they get a DID Document containing your public key:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "verificationMethod": [{
    "id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#keys-1",
    "type": "JsonWebKey2020",
    "controller": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "publicKeyJwk": {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "..."
    }
  }],
  "authentication": ["...#keys-1"],
  "assertionMethod": ["...#keys-1"]
}

This lets anyone verify signatures from your agent without trusting a central authority.

DID Methods Compared¶

Trust Levels¶

Development          Production            Enterprise
───────────          ──────────            ──────────
did:key              did:key               did:key
+ self-signed        + DV badge            + OV/EV badge
     │                    │                      │
     ▼                    ▼                      ▼
Trust Level 0        Trust Level 1-2       Trust Level 3-4

Next Steps¶