Python Quickstart
Five-minute path from pip install to a sign-and-verify loop running entirely in your dev env.
Install
pip install vouch-protocolThe hybrid post-quantum profile (hybrid-eddsa-mldsa44-jcs-2026) is bundled by default; nothing else to install.
Step 1 - Sign and verify locally
Start in your dev env. No domain, no hosting, no internet. Everything runs in your own Python process:
from vouch.keys import generate_identity
from vouch.signer import Signer
from vouch.verifier import Verifier
# Generate an in-memory identity. The "domain" string is just a label
# inside the DID; nothing is published anywhere yet.
identity = generate_identity(domain="localhost")
signer = Signer(
private_key=identity.private_key_jwk,
did=identity.did,
)
token = signer.sign({
"action": "submit_claim",
"target": "claim:HC-001",
"resource": "https://insurance.example.com/claims/HC-001",
})
# trusted_roots is the local-dev escape hatch: in production the verifier
# fetches did.json from the issuer's domain instead.
verifier = Verifier(
trusted_roots={identity.did: identity.public_key_jwk},
allow_did_resolution=False,
)
ok, passport = verifier.check_vouch(token)
assert ok
print("verified intent:", passport.payload)That round-trip is the entire credential layer: keypair, signed action, verified action, all in your own process. No webserver, no public DNS, no .well-known path.
Step 2 - Switch to the modern VC + Data Integrity proof
The legacy JWS form above stays for backward compatibility. New code should prefer the W3C Verifiable Credential form with a Data Integrity proof (eddsa-jcs-2022):
from vouch import build_vouch_credential
credential = build_vouch_credential(
subject_did=identity.did,
intent={
"action": "submit_claim",
"target": "claim:HC-001",
"resource": "https://insurance.example.com/claims/HC-001",
},
valid_seconds=300,
)
signed = signer.sign_credential(credential)
print(signed["proof"]["proofValue"])Verify it with the same Verifier (the credential carries its issuer DID, the Verifier looks up the key in trusted_roots):
import asyncio
from vouch import Verifier
verifier = Verifier(
trusted_roots={identity.did: identity.public_key_jwk},
allow_did_resolution=False,
)
result = asyncio.run(verifier.verify_credential(signed))
print(result.valid, result.reasons)For the hybrid post-quantum profile, swap sign_credential for sign_credential_hybrid. The required pqcrypto library is already bundled with vouch-protocol, so nothing else to install. Everything else stays the same.
Step 3 - When you are ready to publish
The local trial used did:web:localhost and an in-memory keypair. Taking an agent to production is a two-line change:
- Replace
domain="localhost"with a real domain you control. - Publish the DID Document at
https://your-domain/.well-known/did.jsonso any verifier on the internet can resolve it.
Then drop trusted_roots from your Verifier:
# Production: verifier resolves the DID over HTTPS at verification time.
verifier = Verifier()
ok, passport = verifier.check_vouch(token)Generate the production keypair and DID Document with the CLI:
vouch init --domain agent.example.comThat writes the private key into your platform's secure key store (Keychain on macOS, DPAPI on Windows, secret-service on Linux) and emits a did.json you can publish.
What you have now
- A signed-and-verified credential running entirely in a Python REPL
- A modern VC + Data Integrity form, ready for the wire
- A clear two-line upgrade path when you decide to expose the agent to the public internet
Next: try signing with the hybrid post-quantum profile or adding a delegation chain.