The 12-Step Verification Flow¶
AgentPin verifies agent credentials through a comprehensive 12-step protocol. This guide explains each step, shows how to implement custom verification logic, and covers error handling.
Overview¶
When a verifier receives an AgentPin credential (JWT), it performs these steps in order:
| Step | Name | Failure Mode |
|---|---|---|
| 1 | JWT Parsing | ALGORITHM_REJECTED — malformed structure, wrong alg or typ; MALFORMED_CREDENTIAL — claims missing, mistyped or inconsistent |
| 2 | Algorithm Check | ALGORITHM_REJECTED — must be ES256 |
| 3 | Temporal Validation | CREDENTIAL_EXPIRED — exp, iat, nbf, max TTL and credential_ttl_max |
| 4 | Discovery Resolution | DISCOVERY_FETCH_FAILED — cannot fetch/resolve discovery document; DISCOVERY_INVALID — malformed document or non-hostname iss |
| 5 | Signature Verification | SIGNATURE_INVALID — ECDSA signature does not match |
| 6 | Domain Binding | DOMAIN_MISMATCH — normalized issuer domain doesn't match discovery entity |
| 7 | Key Matching | KEY_NOT_FOUND — kid not in discovery document, or key not usable for signatures; KEY_EXPIRED |
| 8 | Agent Status | AGENT_NOT_FOUND / AGENT_INACTIVE |
| 9 | Revocation Checking | CREDENTIAL_REVOKED / AGENT_INACTIVE / KEY_REVOKED; DISCOVERY_INVALID for a malformed or foreign revocation document |
| 10 | Capability Validation | CAPABILITY_EXCEEDED — claimed capabilities exceed declared, or violate the taxonomy |
| 11 | Delegation Chain | DELEGATION_INVALID / DELEGATION_DEPTH_EXCEEDED — chain verification failure, including a chain that cannot be verified |
| 12 | TOFU Key Pinning | KEY_PIN_MISMATCH — key doesn't match previously pinned key |
Step-by-Step Explanation¶
Step 1: JWT Parsing¶
The credential is a compact JWT with three Base64url-encoded segments: header.payload.signature.
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUtMjAyNi0wMSJ9.
eyJpc3MiOiJleGFtcGxlLmNvbSIsInN1YiI6InVybjphZ2VudHBpbjpleGFtcGxlLmNvbTp...
MEUCIQD7y2F8...
The parser splits on ., Base64url-decodes each segment, and validates the JSON structure.
Header fields:
- alg — Algorithm (must be ES256)
- typ — Type (must be agentpin-credential+jwt)
- kid — Key ID (references a key in the discovery document)
Payload fields:
- iss — Issuer domain (e.g., example.com)
- sub — Agent ID URN (e.g., urn:agentpin:example.com:my-agent)
- aud — Audience domain (optional)
- iat — Issued-at timestamp (Unix epoch)
- exp — Expiration timestamp (Unix epoch)
- jti — JWT ID (unique credential identifier)
- capabilities — Array of capability strings
- constraints — Object with constraint fields
- delegation_chain — Array of delegation attestations
Claim shape is validated here: iss/sub/jti must be non-empty strings, iat/exp non-negative integers with exp > iat, capabilities an array of strings and agentpin_version "0.1". Anything else fails with MALFORMED_CREDENTIAL before any cryptography runs. Base64url segments must be strict (no padding, canonical bits).
Step 2: Algorithm Check¶
AgentPin mandates ES256 (ECDSA with P-256) exclusively. Any other algorithm is immediately rejected. This prevents algorithm confusion attacks where an attacker substitutes a weaker algorithm.
// The verifier checks:
if (header.alg !== 'ES256' || header.typ !== 'agentpin-credential+jwt') {
return { valid: false, error_code: 'ALGORITHM_REJECTED' };
}
Step 3: Temporal Validation¶
The verifier checks three timestamps:
import time
now = time.time()
clock_skew = 60 # configurable, default 60 seconds
# Check not expired
if payload["exp"] < now - clock_skew:
raise VerificationError("expired")
# Check issued-at is not in the future
if payload["iat"] > now + clock_skew:
raise VerificationError("not_yet_valid")
# Check TTL doesn't exceed the verifier's cap ...
ttl = payload["exp"] - payload["iat"]
if ttl > max_ttl_secs:
raise VerificationError("CREDENTIAL_EXPIRED")
# ... and, once the agent is found (step 8), the agent's own declared cap
if ttl > agent.get("credential_ttl_max", 86400):
raise VerificationError("CREDENTIAL_EXPIRED")
Best practice: Use short-lived credentials (hours, not days). The default maximum TTL is 86400 seconds (24 hours), and the agent declaration's credential_ttl_max (spec §5.7) is enforced as a second, per-agent cap.
Step 4: Discovery Resolution¶
The verifier extracts the iss (issuer) claim, normalizes it (lowercase, one trailing dot removed, IDNA A-labels) and rejects anything that is not a bare hostname — a scheme, port, path, userinfo or IP literal fails with DISCOVERY_INVALID before any request is sent. It then resolves the discovery document. Resolution can happen via:
- Online — Fetch
https://{iss}/.well-known/agent-identity.jsonover HTTPS - Offline — Use a pre-provided discovery document
- Trust bundle — Look up the domain in a pre-loaded trust bundle
- Local file — Read from a local directory (
{domain}.json)
// Online resolution
const response = await fetch(
`https://${issuer}/.well-known/agent-identity.json`,
{ redirect: 'error' } // MUST NOT follow redirects
);
const discovery = await response.json();
HTTP redirects are rejected to prevent redirect-based attacks; every fetch has a 10 s timeout, a 1 MiB body cap and requires a JSON content type.
Step 5: Signature Verification¶
The verifier resolves the public key using the kid from the JWT header, then verifies the ES256 signature over the header.payload portion of the JWT.
from agentpin import find_key_by_kid, jwk_to_pem, verify_jwt
# Find the public key matching the kid; it must be a usable signature key
# (use == "sig", key_ops includes "verify" when present, exp not passed)
jwk = find_key_by_kid(discovery, header["kid"])
if jwk is None:
raise VerificationError("KEY_NOT_FOUND")
# Verify the ECDSA signature over "<header>.<payload>" (DER-encoded signature)
verify_jwt(credential_jwt, jwk_to_pem(jwk))
Step 6: Domain Binding¶
The normalized iss claim in the JWT must match the normalized entity field in the discovery document, and the document's revocation_endpoint / a2a_endpoint (when present) must be https:// URLs on that same host:
if (normalizeDomain(payload.iss) !== normalizeDomain(discovery.entity)) {
return { valid: false, error_code: 'DOMAIN_MISMATCH' };
}
Step 7: Key Matching¶
The kid from the JWT header must reference a key declared in the discovery document's public_keys array.
Step 8: Agent Status¶
The sub (agent_id) claim must reference an agent declared in the discovery document with status: "active":
agent = None
for a in discovery["agents"]:
if a["agent_id"] == payload["sub"]:
agent = a
break
if agent is None or agent["status"] != "active":
raise VerificationError("AGENT_INACTIVE")
Step 9: Revocation Checking¶
The verifier checks the revocation document (if available) for three revocation types:
// The document is validated structurally first: it must belong to the issuer
// (entity), every entry must carry its identifying field, and a signature
// (if present) must verify under a discovery key — otherwise DISCOVERY_INVALID.
// Check credential-level revocation (by jti)
if (revocation.revoked_credentials?.some(r => r.jti === payload.jti)) {
return { valid: false, error_code: 'CREDENTIAL_REVOKED' };
}
// Check agent-level revocation (by agent_id)
if (revocation.revoked_agents?.some(r => r.agent_id === payload.sub)) {
return { valid: false, error_code: 'AGENT_INACTIVE' };
}
// Check key-level revocation (by kid)
if (revocation.revoked_keys?.some(r => r.kid === header.kid)) {
return { valid: false, error_code: 'KEY_REVOKED' };
}
Step 10: Capability Validation¶
Capabilities in the credential must be a subset of capabilities declared for the agent in the discovery document:
from agentpin import capabilities_subset
if not capabilities_subset(agent["capabilities"], payload["capabilities"]):
raise VerificationError("CAPABILITY_EXCEEDED")
Wildcard capabilities (read:*) in the discovery document match any specific capability (read:data, read:logs). admin:* is never accepted, and with strict_capabilities (the default) every capability must follow the §10 taxonomy. Constraints are then merged: the credential may only narrow the discovery declaration's constraints, and the result carries the effective (merged) set.
Step 11: Delegation Chain Verification¶
If the credential includes a delegation chain, the verifier walks the chain to confirm both software provenance (Maker) and operational authorization (Deployer):
- Resolve the attester's discovery document (through the same resolver used for the issuer, a dedicated chain resolver, a trust bundle, or pre-fetched over HTTPS)
- Verify the attestation signature with the attester's key (
kid) over the domain-separated attestation input, with delegatee = the credential'siss/suband the credential's capabilities - Confirm capabilities narrow (never widen): the credential's capabilities must be within what the attester declares for the attested agent, which must be active
- Check delegation depth doesn't exceed the minimum
max_delegation_depthacross all participants
for (const link of payload.delegation_chain) {
const attesterDoc = chainResolver.resolveDiscovery(normalizeDomain(link.domain));
const key = findKeyByKid(attesterDoc, link.kid);
verifyAttestation(link, jwkToPem(key), payload.iss, payload.sub, payload.capabilities);
// Capabilities must narrow at each level
validateCredentialAgainstDiscovery(payload.capabilities, findAgentById(attesterDoc, link.agent_id).capabilities);
}
verifyChainDepth(payload.delegation_chain.length, [discovery.max_delegation_depth, ...attesterDepths]);
A chain that cannot be verified (for example offline with no chain resolver) is rejected with DELEGATION_INVALID. Only with require_delegation_verification set to false is such a credential accepted, and then the result carries delegation_verified: false and a warning.
Step 12: TOFU Key Pinning¶
Trust-On-First-Use: The first time a key is seen for a domain, it is pinned. Subsequent verifications check that the same key is used.
from agentpin import KeyPinStore, PinningResult
pin_store = KeyPinStore()
result = pin_store.check_and_pin(issuer_domain, public_key_jwk)
if result == PinningResult.FIRST_USE:
# First time seeing this domain — key is now pinned
pass
elif result == PinningResult.MATCHED:
# Key matches previously pinned key
pass
elif result == PinningResult.CHANGED:
# KEY CHANGED — possible attack
raise VerificationError("KEY_PIN_MISMATCH")
Pins are keyed on the normalized issuer domain, so case variants and trailing dots share one pin set.
Verification Result¶
The verification result includes:
{
"valid": true,
"agent_id": "urn:agentpin:example.com:my-agent",
"issuer": "example.com",
"capabilities": ["read:data", "write:reports"],
"constraints": { "allowed_domains": ["*.client-corp.com"], "rate_limit": "100/hour" },
"delegation_verified": true,
"delegation_chain": [ { "domain": "maker.com", "role": "maker", "verified": true } ],
"key_pinning": { "status": "first_use", "first_seen": "2026-02-15T12:00:00Z" },
"warnings": []
}
| Field | Type | Description |
|---|---|---|
valid |
boolean | Overall verification result. true only when every present feature verified (strict result) |
agent_id |
string | Verified agent identifier (URN) |
issuer |
string | Verified issuer domain (normalized) |
capabilities |
array | Validated capabilities |
constraints |
object | Effective constraints: discovery defaults narrowed by the credential |
delegation_verified |
boolean | Whether the delegation chain verified (absent when no chain) |
delegation_chain |
array | One {domain, role, verified} entry per attestation |
key_pinning |
object | {"status": "first_use" \| "pinned", "first_seen": ...} |
error_code |
string | Error code if valid is false |
error_message |
string | Human-readable error description |
warnings |
array | Non-fatal notes (only non-empty with explicit opt-outs) |
Configuration Options¶
Both JavaScript and Python verifiers accept a configuration object:
JavaScript¶
const config = {
clockSkewSecs: 60, // allowed clock skew (default: 60)
maxTtlSecs: 86400, // maximum credential TTL (default: 86400)
strictCapabilities: true, // enforce the capability taxonomy (default: true)
requireDelegationVerification: true, // reject chains that cannot be verified (default: true)
requireSignedRevocation: false, // reject unsigned revocation documents (default: false)
revocationMaxAgeSecs: null, // reject stale revocation documents when set
};
const result = verifyCredentialOffline(jwt, discovery, null, pinStore, audience, config);
Python¶
from agentpin import VerifierConfig
config = VerifierConfig(
clock_skew_secs=60,
max_ttl_secs=86400,
strict_capabilities=True,
require_delegation_verification=True,
require_signed_revocation=False,
revocation_max_age_secs=None,
)
result = verify_credential_offline(jwt, discovery, None, pin_store, audience, config)
Error Handling¶
All verification errors include an error_code and error_message:
| Error Code | Meaning | Action |
|---|---|---|
ALGORITHM_REJECTED |
JWT structure, alg or typ is wrong |
Only ES256 agentpin-credential+jwt credentials are accepted |
MALFORMED_CREDENTIAL |
Claims missing, mistyped or inconsistent | Check the issuer's claim set |
CREDENTIAL_EXPIRED |
Expired, not yet valid, or lifetime over a cap | Issue a new credential |
DISCOVERY_FETCH_FAILED |
Cannot resolve discovery or revocation document | Check domain and network |
DISCOVERY_INVALID |
Discovery/revocation document failed validation, or iss is not a hostname |
Fix the published documents |
SIGNATURE_INVALID |
Signature verification failed | Credential may be tampered |
DOMAIN_MISMATCH |
Issuer doesn't match discovery entity | Possible impersonation |
KEY_NOT_FOUND |
kid not in discovery document, or key not usable for signatures |
Key may have been rotated |
KEY_EXPIRED |
Key exp passed or unparsable |
Rotate the key |
AGENT_NOT_FOUND / AGENT_INACTIVE |
Agent not declared / not active | Agent may be suspended |
CREDENTIAL_REVOKED / KEY_REVOKED |
Credential or key is revoked | Do not trust this credential |
CAPABILITY_EXCEEDED |
Capabilities exceed declared scope or violate the taxonomy | Possible capability inflation |
CONSTRAINT_VIOLATION |
Credential widens a discovery constraint | Narrow the credential's constraints |
DELEGATION_INVALID / DELEGATION_DEPTH_EXCEEDED |
Delegation chain verification failed or could not be performed | Check chain integrity |
AUDIENCE_MISMATCH |
aud does not match the verifier |
Issue for the right audience |
KEY_PIN_MISMATCH |
TOFU pin violation | Possible key substitution attack |