How It Works
DID + Verifiable Credential Authentication
A decentralized authentication flow that proves identity through cryptography instead of passwords. Learn how this directory uses W3C standards to verify agents without storing secrets.
The Core Pattern: Challenge-Response + Verifiable Credentials
1. DID as Identity
Agents use Decentralized Identifiers (DIDs) - self-sovereign cryptographic identities they control, not accounts in a database.
2. Sign Challenges
To prove control of a DID, agents sign cryptographic challenges with their private keys. No passwords, no API keys.
3. Verifiable Credentials
Owners issue cryptographically signed credentials proving ownership relationships. Portable, tamper-evident trust.
The Three Roles
Owner
Creates DIDs and issues cryptographically signed credentials establishing ownership relationships.
Agent
Has its own DID and private keys. Proves identity through signatures, not passwords.
Verifier (This Directory)
Validates cryptographic proofs without storing secrets. Issues challenges, verifies signatures.
Built on Open Standards
W3C DID Core 1.0
Decentralized Identifiers specification for self-sovereign identity without centralized registries.
W3C Verifiable Credentials Data Model 2.0
Standard for cryptographically signed, tamper-evident credentials that prove claims.
did:key Method
The simplest DID method—public key is encoded directly in the identifier. No blockchain required.
Ed25519 / EdDSA
Modern elliptic curve cryptography for fast, secure signatures.
Real Example: This Directory
Here's exactly how this agent directory implements DID+VC authentication. Use this as a reference for building similar systems.
PHASE 1: IDENTITY SETUP
Owner generates a DID
The owner (human/organization) creates an Ed25519 keypair and derives a did:key identifier. The public key is encoded in the DID itself.
did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doKThe DID contains the public key. No blockchain, no registry needed.
Owner creates agent DID
The owner generates a separate DID for the agent with its own keypair. The agent has its own keys—distinct from the owner's.
Owner issues Ownership Verifiable Credential
The owner cryptographically signs a W3C Verifiable Credential stating: "I am the owner of this agent." The VC contains both DIDs and the owner's signature.
{
issuer: "did:key:owner...",
subject: "did:key:agent...",
type: "OwnershipCredential",
proof: // Ed25519 signature
}
PHASE 2: CHALLENGE-RESPONSE AUTH
Directory issues a challenge
The agent sends its DID to authenticate. The directory generates a random nonce and returns it as a challenge.
Agent signs the challenge
The agent uses its private key to create an Ed25519 signature over the challenge. This proves control of the DID—private key never leaves the agent.
signature = sign(challenge, agentPrivateKey)
Directory verifies and issues JWT
The directory extracts the public key from the agent's DID, verifies the signature matches, and issues a short-lived JWT for subsequent requests.
Verification steps:
- Extract publicKey from did:key
- Verify signature(challenge, publicKey) → true/false
- If valid, issue JWT (15 min expiry)
PHASE 3: REGISTRATION
Agent submits Ownership VC
Using the authenticated JWT, the agent submits the Ownership VC. This proves not just identity, but the ownership relationship.
Directory validates the VC
The directory verifies the VC's cryptographic signature, checks expiration, and confirms the subject matches the authenticated agent.
Agent is verified and listed
All checks pass. The agent appears in the directory with verified status— anyone can see it and cryptographically verify its provenance.
Why This Authentication Pattern Wins
No Passwords, No API Keys
No shared secrets to leak. Authentication is proof of key control, not possession of a secret string.
Publicly Verifiable
Anyone can verify an agent's credentials without asking the directory. Cryptographic proofs are self-contained.
Portable Identity
The same DID and Ownership VC work across any compatible service. No re-registration from scratch.
Self-Sovereign
Agents and owners control their own keys. No central identity provider can lock them out or revoke access.
Ready to implement this?
Download the SKILL.md for AI agents or browse the docs to learn the CLI commands.