Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 52 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
KAPI (KERI Application Programming Interface) is the comprehensive set of standardized APIs designed for KERI ecosystem components (Controllers, Agents, Witnesses, Watchers, Registrars) that preserve KERI's unique protocol properties including self-certifying identifiers, key event log verifiability, witness agreement mechanisms, end-to-end verifiability, and duplicity detection capabilities.
KAPI represents the standardized application programming interface layer for the KERI (Key Event Receipt Infrastructure) ecosystem. Unlike traditional APIs that merely expose functionality, KAPI is specifically architected to preserve and propagate KERI's unique security properties across component boundaries. This preservation requirement fundamentally shapes KAPI's design philosophy: every API endpoint, message format, and interaction pattern must maintain KERI's cryptographic guarantees including self-certifying identifiers, key event log integrity, witness agreement protocols, and duplicity detection mechanisms.
The primary specification repository is hosted at github.com/WebOfTrust/kapi, which serves as the authoritative reference for KAPI design patterns and implementation requirements. KAPI emerged from the recognition that KERI's revolutionary approach to decentralized key management infrastructure requires equally revolutionary API design—one that doesn't compromise KERI's security model for convenience or compatibility with legacy systems.
KAPI serves three fundamental objectives within the KERI ecosystem:
When implementing KAPI-compliant APIs, developers must adhere to several core principles:
1. Security Property Preservation: Every API endpoint must maintain KERI's security guarantees. This means:
2. CESR Encoding Compliance: All cryptographic primitives and events must be encoded using CESR:
3. Asynchronous Event Handling: KAPI implementations must handle asynchronous, out-of-order events:
4. State Management: Proper state management is critical:
Developers should study existing KAPI implementations:
KERIA (Python): The KERIA agent service demonstrates:
Signify (TypeScript): The Signify client library shows:
KERIpy (Python): The reference implementation provides:
The design philosophy explicitly rejects the "lowest common denominator" approach typical of cross-platform APIs. Instead, KAPI embraces KERI's sophisticated security model as a non-negotiable baseline, requiring all implementations to support the full protocol rather than offering degraded compatibility modes.
As of the latest documentation (2025), KAPI exists as a community-driven specification rather than a formal IETF RFC. However, it builds directly upon the KERI protocol specification currently progressing through IETF standardization (draft-ssmith-keri). KAPI's specification approach follows the KERI community's pattern of implementation-driven standardization, where multiple working implementations inform specification refinement rather than specification preceding implementation.
The KAPI specification explicitly references and depends upon:
KAPI's evolution tracks closely with KERI protocol maturation:
Early Phase (2020-2021): Initial KAPI concepts emerged during KERIpy development, focusing on internal component APIs within the Python reference implementation. These early APIs were tightly coupled to Python-specific patterns and not designed for cross-language interoperability.
Formalization Phase (2022-2023): The emergence of multiple KERI implementations (KERIox in Rust, KERIml in Swift) created urgent need for standardized APIs. The KERIA (KERI Agent) project drove significant KAPI design work, establishing patterns for agent-based architectures and REST API conventions. The vLEI (verifiable Legal Entity Identifier) production deployment by GLEIF provided critical real-world validation of KAPI patterns under enterprise requirements.
Current Phase (2024-2025): KAPI has matured into a comprehensive specification covering the full KERI component ecosystem. The Signify client library and KERIA server represent the current reference architecture, demonstrating KAPI's ability to support both lightweight browser-based clients and high-performance cloud agents. The specification now addresses advanced scenarios including multi-signature group identifiers, delegated identifiers, and transaction event logs for credential registries.
KAPI defines APIs for six primary component categories within the KERI ecosystem:
1. Controllers: Entities that manage AIDs (Autonomic Identifiers) and perform cryptographic operations. Controllers may be:
2. Agents: Software services that act on behalf of controllers, typically providing:
The KERIA implementation exemplifies the agent architecture, exposing three distinct network interfaces:
3. Witnesses: Designated entities that:
Witness APIs must support:
4. Watchers: Validator-selected entities operating in promiscuous mode that:
Watcher APIs emphasize:
5. Registrars: Entities managing transaction event logs for credential registries:
6. Verifiers: Applications and services that:
KAPI implements a three-layer architecture that mirrors KERI's protocol stack:
Layer 1: Cryptographic Primitives Layer
This foundational layer provides APIs for:
APIs at this layer must support:
Layer 2: Event Processing Layer
This layer handles KERI event lifecycle:
Layer 3: Protocol Interaction Layer
The highest layer orchestrates multi-party protocols:
KAPI's data flow architecture emphasizes asynchronous, event-driven patterns that align with KERI's distributed nature:
Outbound Flow (Controller → Network):
Inbound Flow (Network → Controller):
Query Flow (Verifier → Network):
KAPI components maintain several categories of state:
Persistent State:
Ephemeral State:
Computed State:
KAPI's state management follows RUN (Read, Update, Nullify) semantics rather than traditional CRUD, reflecting KERI's append-only architecture where events are never deleted, only superseded.
KAPI mandates CESR (Composable Event Streaming Representation) as the canonical encoding for all KERI protocol messages. CESR provides:
Dual-Domain Encoding: Messages can be represented in either:
Self-Framing Primitives: Each CESR primitive includes:
Group Codes: CESR supports count codes that frame groups of primitives, enabling:
KAPI defines several fundamental message categories:
1. Key Event Messages
All key events share a common structure:
{
"v": "KERI10JSON00011c_", // Version string
"t": "icp", // Event type (ilk)
"d": "EBabiu_JCkE0GbiglDX...", // Event SAID
"i": "EBabiu_JCkE0GbiglDX...", // Identifier prefix
"s": "0", // Sequence number
"kt": "1", // Signing threshold
"k": ["DaU6JR2nmwyZ-i0d8..."], // Current keys
"nt": "1", // Next threshold
"n": ["EQb3zXwY6QGZqGx9..."], // Next key digests
"bt": "2", // Witness threshold
"b": ["BGKVzj4ve0VSd8z_..."], // Witness identifiers
"c": [], // Configuration traits
"a": [] // Anchored data seals
}
Field Semantics:
v: Version string specifying KERI version and serialization formatt: Event type (ilk) - icp (inception), rot (rotation), ixn (interaction), dip (delegated inception), drt (delegated rotation)d: SAID (Self-Addressing Identifier) of the eventi: AID prefix being manageds: Sequence number (hexadecimal string)kt: Current threshold for signingk: List of current public keys (qualified CESR primitives)nt: Next threshold for rotationn: List of next key digests (cryptographic commitments)bt: Witness threshold (TOAD)b: List of witness AIDsc: Configuration traits (optional features)a: Seals anchoring external data2. Receipt Messages
{
"v": "KERI10JSON00011c_",
"t": "rct",
"d": "EBabiu_JCkE0GbiglDX...", // Event being receipted
"i": "BGKVzj4ve0VSd8z_..." // Witness identifier
}
Receipts are typically transmitted with indexed signatures attached via CESR count codes.
3. OOBI Messages
Out-Of-Band Introductions enable identifier discovery:
URL Format:
http://witness.example.com/oobi/EBabiu_JCkE0GbiglDX.../witness/BGKVzj4ve0VSd8z_...
JSON Format:
{
"eid": "EBabiu_JCkE0GbiglDX...", // Identifier
"scheme": "http",
"url": "http://witness.example.com:5642/",
"role": "witness" // or "controller", "watcher", etc.
}
4. IPEX Messages
Issuance and Presentation Exchange messages use KERI exchange events:
{
"v": "KERI10JSON00011c_",
"t": "exn",
"d": "EBabiu_JCkE0GbiglDX...",
"i": "EBabiu_JCkE0GbiglDX...", // Sender AID
"p": "", // Prior event digest
"dt": "2024-01-15T10:30:00.000000+00:00",
"r": "/ipex/grant", // Route
"q": {}, // Query parameters
"a": { // Payload
"m": "Grant message",
"acdc": { /* ACDC credential */ }
}
}
5. TEL Messages
Transaction Event Log messages track credential status:
{
"v": "KERI10JSON00011c_",
"t": "iss", // Issuance event
"d": "EBabiu_JCkE0GbiglDX...",
"i": "EBabiu_JCkE0GbiglDX...", // Registry identifier
"s": "0",
"ri": "EQb3zXwY6QGZqGx9...", // Credential SAID
"dt": "2024-01-15T10:30:00.000000+00:00"
}
KAPI supports multiple serialization formats via CESR interleaving:
JSON: Human-readable, widely supported
CBOR: Compact binary format
MessagePack: Alternative binary format
Pure CESR: Native KERI encoding
KAPI uses CESR count codes to attach signatures and receipts:
Signature Attachment:
{event_json}-AABAABabiu_JCkE0GbiglDX... // Indexed signature
Receipt Attachment:
{event_json}-VAS-GAB0AAAAAAAAAAAAAAAAAAAAABabiu... // Receipt with witness signature
Multiple Attachments:
{event_json}-AABAABabiu...-AABAAQb3zX...-VAS-GAB0AA... // Multiple signatures and receipt
This attachment pattern enables pipelining where multiple events with attachments can be concatenated in a single stream while maintaining individual event boundaries.
Creating a new AID involves coordinated API calls:
1. Key Generation
API: generate_keypairs(count=1, next_count=1, algorithm="Ed25519")
Returns: {
"current": [{"public": "...", "private": "..."}],
"next": [{"public": "...", "private": "..."}]
}
2. Inception Event Creation
API: create_inception(
keys=["DaU6JR2nmwyZ..."],
next_digests=["EQb3zXwY6QGZ..."],
witnesses=["BGKVzj4ve0VSd8z_...", ...],
witness_threshold=2
)
Returns: {
"event": {/* inception event */},
"prefix": "EBabiu_JCkE0GbiglDX..."
}
3. Event Signing
API: sign_event(event, private_keys)
Returns: {
"event": {/* event */},
"signatures": ["AABabiu_JCkE0GbiglDX..."]
}
4. Witness Promulgation
API: send_to_witnesses(signed_event, witness_endpoints)
Returns: {
"receipts": [{/* receipt from witness 1 */}, ...],
"threshold_met": true
}
5. KEL Storage
API: store_event(event, signatures, receipts)
Returns: {"stored": true, "sequence": "0"}
Rotation events update key state:
1. Generate New Keys
API: generate_keypairs(count=1, next_count=1)
2. Create Rotation Event
API: create_rotation(
identifier="EBabiu_JCkE0GbiglDX...",
sequence="1",
previous_digest="EBabiu_JCkE0GbiglDX...",
keys=["DnewKey123..."],
next_digests=["EnextKey456..."],
witnesses=[...], // Can change witness set
witness_threshold=2,
witness_adds=[], // New witnesses
witness_cuts=[] // Removed witnesses
)
3. Sign with Pre-Rotated Keys
API: sign_event(rotation_event, pre_rotated_private_keys)
Critical: Rotation events MUST be signed with the pre-rotated keys committed in the previous event, not the current signing keys.
4. Promulgate and Receipt
API: send_to_witnesses(signed_rotation)
Group multi-sig identifiers require coordination:
2. Group Inception
API: create_group_inception(
participants=[
{"aid": "EParticipant1...", "weight": "1"},
{"aid": "EParticipant2...", "weight": "1"}
],
threshold="2", // 2-of-2 multisig
witnesses=[...]
)
3. Signature Collection Each participant signs the group inception event:
API: sign_event(group_inception, participant_private_key)
Signatures are collected until threshold is met.
4. Event Finalization
API: finalize_multisig_event(
event=group_inception,
signatures=[sig1, sig2]
)
5. Witness Promulgation Once threshold signatures are collected, the event is sent to witnesses.
OOBI resolution enables identifier discovery:
1. OOBI Reception
API: receive_oobi(
"http://witness.example.com/oobi/EBabiu_JCkE0GbiglDX.../witness/BGKVzj4ve0VSd8z_..."
)
2. Endpoint Discovery KAPI parses the OOBI to extract:
3. KEL Retrieval
API: fetch_kel(
identifier="EBabiu_JCkE0GbiglDX...",
endpoint="http://witness.example.com"
)
Returns: {"kel": [{/* inception */}, {/* rotation */}, ...]}
4. KEL Validation
API: validate_kel(kel)
Returns: {
"valid": true,
"key_state": {/* current key state */}
}
5. Caching Validated key state is cached for future use.
IPEX orchestrates credential issuance and presentation:
Issuance Flow:
1. Credential Creation
API: create_acdc(
issuer="EIssuer123...",
issuee="EIssuee456...",
schema="ESchema789...",
attributes={/* credential data */}
)
2. Grant Message
API: create_ipex_grant(
sender="EIssuer123...",
recipient="EIssuee456...",
acdc={/* credential */}
)
3. Transmission
API: send_ipex_message(grant_message, recipient_endpoint)
Presentation Flow:
1. Presentation Request
API: create_ipex_apply(
sender="EVerifier123...",
recipient="EHolder456...",
schema="ESchema789..." // Requested credential type
)
2. Credential Selection
API: select_credentials(
schema="ESchema789...",
holder="EHolder456..."
)
Returns: [{/* matching credentials */}]
3. Presentation Creation
API: create_ipex_offer(
sender="EHolder456...",
recipient="EVerifier123...",
acdc={/* selected credential */}
)
4. Verification
API: verify_presentation(
presentation={/* IPEX offer */}
)
Returns: {
"valid": true,
"issuer_verified": true,
"holder_verified": true,
"not_revoked": true
}
Transaction Event Logs track credential status:
1. Registry Discovery
API: resolve_registry(
credential_said="ECredential123..."
)
Returns: {
"registry_aid": "ERegistry456...",
"backers": ["EBacker1...", "EBacker2..."]
}
2. Status Query
API: query_credential_status(
credential_said="ECredential123...",
registry_aid="ERegistry456..."
)
Returns: {
"status": "issued", // or "revoked"
"issued_at": "2024-01-15T10:30:00Z",
"revoked_at": null
}
3. TEL Verification
API: verify_tel(
tel=[{/* issuance event */}, ...],
registry_aid="ERegistry456..."
)
Returns: {"valid": true}
KAPI's security design addresses multiple threat categories:
1. Network Adversaries
2. Compromised Components
3. Key Compromise
KAPI preserves KERI's core security properties:
KAPI's design resists specific attack vectors:
Sybil Attacks
Replay Attacks
KAPI is fundamentally dependent on the KERI protocol stack:
KAPI provides integration with external systems:
did:keri: Native KERI DID methoddid:webs: Web-based KERI identifiers with KERI event streamsTransport Protocols
Storage Backends
Cryptographic Libraries
1. Asynchronous Event Processing
KERI's distributed nature requires handling out-of-order events:
2. Witness Coordination
Coordinating with multiple witnesses introduces complexity:
3. Key Management
Secure key storage is critical:
4. State Synchronization
Maintaining consistent key state across components:
5. Performance Optimization
Balancing security with performance:
Signature Operations
KEL Processing
Network Latency
Storage Requirements
Horizontal Scaling
Caching Strategies
Batching Operations
Key Generation
Key Storage
Network Security
Operational Security
Unit Testing
Integration Testing
Security Testing
Performance Testing
Client-Side Deployment
Server-Side Deployment
Hybrid Deployment
KAPI represents a comprehensive API framework specifically designed to preserve and propagate KERI's revolutionary security properties across distributed components. By mandating CESR encoding, supporting asynchronous event processing, and enabling witness coordination, KAPI provides the essential infrastructure for building secure, scalable, and interoperable KERI-based applications.
The API's design reflects KERI's core philosophy: cryptographic security should not be compromised for convenience. Every KAPI endpoint, message format, and interaction pattern maintains KERI's guarantees around self-certifying identifiers, key event log integrity, duplicity detection, and end-to-end verifiability.
As the KERI ecosystem continues to mature, KAPI will evolve to support new use cases while maintaining backward compatibility and security guarantees. The specification's implementation-driven approach ensures that KAPI remains practical and deployable while advancing the state of decentralized identity infrastructure.
KAPI implementations should include comprehensive test suites:
Protocol Compliance Tests:
Security Tests:
Integration Tests:
Performance Tests:
Client-Side Deployments:
Server-Side Deployments:
Hybrid Deployments:
1. Improper Key Management: Never store private keys unencrypted or transmit them over networks.
2. Ignoring Asynchronous Nature: Don't assume events arrive in order; implement proper escrow mechanisms.
3. Weak Witness Coordination: Ensure TOAD thresholds are properly enforced and receipts are validated.
4. Inadequate Duplicity Detection: Always check for conflicting events via watcher queries.
5. Performance Shortcuts: Don't skip signature verification or KEL validation for performance; use caching instead.
KAPI will continue evolving to support:
Developers should monitor the KAPI GitHub repository for specification updates and participate in the KERI community to influence future development.