Interactive Guide: Agent Identity with Python

The Problem: AI Agent Impersonation

As AI agents become more autonomous and interact with external services, a critical question arises: how do you know which agent you're talking to?

Without cryptographic identity, any agent can claim to be any other agent. A malicious actor could deploy an agent that impersonates a trusted service, exfiltrating data or performing unauthorized actions.

AgentPin solves this with domain-anchored cryptographic credentials — ES256 JWTs tied to discoverable public keys, with capability scoping, delegation chains, and TOFU key pinning.

Step 1: Install

pip install agentpin

Step 2: Generate Keys

Generate an ECDSA P-256 keypair for signing credentials.

from agentpin import generate_key_pair, generate_key_id

# Generate keypair
private_key_pem, public_key_pem = generate_key_pair()
kid = generate_key_id(public_key_pem)

print(f"Key ID: {kid}")
print(f"Private key:\n{private_key_pem}")
print(f"Public key:\n{public_key_pem}")

Step 3: Issue a Credential

Issue a signed JWT credential for your agent with specific capabilities.

from agentpin import issue_credential, Capability

credential = issue_credential(
    private_key_pem=private_key_pem,
    kid=kid,
    issuer="example.com",
    agent_id="urn:agentpin:example.com:my-agent",
    audience="verifier.com",
    capabilities=[
        Capability.create("read", "data"),
        Capability.create("write", "reports"),
    ],
    constraints={"rate_limit": "100/minute"},
    delegation_chain=None,
    ttl_secs=3600,
)

print(f"Credential JWT: {credential}")

Step 4: Verify a Credential

Verify a credential offline (with a local discovery document) or online (auto-fetching from the issuer's domain).

from agentpin import (
    verify_credential_offline,
    verify_credential,
    KeyPinStore,
    VerifierConfig,
)

pin_store = KeyPinStore()
config = VerifierConfig(clock_skew_secs=60, max_ttl_secs=86400)

# Offline verification (with local discovery doc)
result = verify_credential_offline(
    credential_jwt=credential,
    discovery=discovery_document,
    revocation=None,
    pin_store=pin_store,
    audience="verifier.com",
    config=config,
)

if result.valid:
    print(f"Agent: {result.agent_id}")
    print(f"Issuer: {result.issuer}")
    print(f"Capabilities: {result.capabilities}")
else:
    print(f"Failed: {result.error_code} - {result.error_message}")

# Online verification (auto-fetches discovery)
online_result = verify_credential(
    credential_jwt=credential,
    pin_store=pin_store,
    audience="verifier.com",
    config=config,
)

Verification Result

Valid Credential

Expired / Revoked

result.valid = True
result.agent_id    = "urn:agentpin:example.com:my-agent"
result.issuer      = "example.com"
result.capabilities = ["read:data", "write:reports"]
result.key_pinning  = {"status": "first_use"}