Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 25 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.
A custodial agent is an agent owned by an individual who has granted signing authority to a custodian (typically also the host of the agent software), while retaining exclusive rotation authority through KERI's partial rotation mechanism, enabling the owner to unilaterally revoke the custodian's privileges without requiring cooperation.
A custodial agent represents a sophisticated key management pattern that addresses one of the most significant barriers to mainstream adoption of decentralized identity systems: the tension between user sovereignty and practical usability. At its core, a custodial agent is an agent owned by an individual but operated by a third-party custodian who hosts the running agent software and holds signing authority for day-to-day operations.
The defining characteristic that distinguishes custodial agents from traditional custodial arrangements is the split of control authority into two distinct capabilities:
This separation enables the identifier owner to "fire" the custodian at any time without requiring the custodian's cooperation—a critical capability that preserves user sovereignty while enabling professionally managed services.
Traditional custodial arrangements in digital identity and cryptocurrency systems typically involve complete transfer of control to the service provider. Users who lack technical expertise or confidence in managing cryptographic keys must choose between:
Implementing custodial agent arrangements requires careful attention to:
Authority Separation: Ensure that rotation authority keys are never shared with or accessible to the custodian. These keys should be stored separately, ideally in cold storage or hardware security modules under the owner's exclusive control.
Threshold Configuration: Structure signing and rotation thresholds to enforce the authority split. For example, a 1-of-1 threshold for signing authority (custodian's key) and a separate 1-of-1 threshold for rotation authority (owner's pre-rotated key).
Service Level Agreements: Define clear expectations for custodian responsibilities, availability guarantees, and procedures for service termination or migration.
Key Recovery Procedures: Establish processes for the owner to exercise rotation authority in various scenarios (routine migration, custodian compromise, service termination, etc.).
Audit and Accountability: Implement mechanisms for the owner to monitor custodian signing operations and detect unauthorized or incorrect behavior.
Custodial agents support multiple adoption patterns:
Onboarding Path: New users can start with fully custodial arrangements and gradually transition to self-custody as they gain confidence and technical capability.
Hybrid Models: Sophisticated users can maintain both custodial agents (for convenience) and self-custody arrangements (for high-value operations) using the same identifier.
Enterprise Delegation: Organizations can delegate operational signing to departments or employees while maintaining executive control through rotation authority.
Regulatory Compliance: Custodial arrangements can satisfy regulatory requirements for professional key management while preserving user sovereignty through retained rotation authority.
This binary choice has been a fundamental barrier to mainstream adoption. In traditional custodial models, users who want to change providers or reclaim direct control must rely on the custodian's cooperation, creating vendor lock-in and centralization of power.
In blockchain-based systems, custodial wallets became popular because they eliminated the need for users to manage seed phrases and private keys directly. However, these arrangements often meant users had no cryptographic proof of ownership independent of the custodian's systems—"not your keys, not your coins" became a warning about the risks of custodial arrangements.
KERI solves this dilemma through its partial rotation mechanism, which enables cryptographic separation of signing and rotation authorities. This is implemented through KERI's dual-key architecture:
KERI's establishment events support two distinct key sets:
By structuring the thresholds and key lists appropriately, a controller can:
The critical security property is that the identifier owner can exercise their rotation authority to:
This is possible because rotation events are signed with the pre-rotated keys that only the owner possesses. The custodian's signing keys are explicitly excluded from the rotation authority threshold, preventing them from blocking or interfering with the owner's exercise of ultimate control.
KERI defines custodial rotation as a specific type of rotation operation that:
This enables flexible transitions between custodial arrangements, self-custody, and hybrid models without breaking the identifier's verifiable history.
The source documents emphasize that 99% of people may not feel comfortable taking direct responsibility for managing cryptographic keys and agent software. Custodial agents address this reality by:
Custodial agents enable a SaaS business model without centralizing control. Service providers can:
All while users maintain the cryptographic capability to migrate to different providers or self-custody at will.
The custodial agent security model provides important properties:
Compartmentalized Risk: Even if the custodian's signing keys are compromised, the attacker cannot:
The owner's pre-rotated keys remain the ultimate authority, enabling recovery from custodian compromise.
Operational Flexibility: Organizations can:
Trust Minimization: Users can benefit from custodial services without:
Custodial agents are particularly valuable for:
While custodial agents solve critical adoption challenges, they involve trade-offs:
Operational Dependence: Users depend on the custodian for day-to-day signing operations. If the custodian becomes unavailable, the user cannot sign transactions until they exercise rotation authority to establish new signing keys.
Privacy Considerations: The custodian can observe all signing operations, potentially learning about the user's activities and relationships. This is inherent to the custodial model but should be considered in privacy-sensitive applications.
Key Management Responsibility: While signing key management is delegated, users must still protect their rotation authority keys. Loss of these keys means loss of the ability to revoke the custodian or recover from custodian compromise.
Trust in Custodian Operations: While the custodian cannot lock out the owner, they can refuse to sign or perform operations incorrectly. Users must trust the custodian to operate honestly within their granted authority, though cryptographic accountability mechanisms can detect misbehavior.
Custodial agents are identified in the source documents as a key feature for KERI and ACDC adoption because they solve the fundamental tension between:
This makes custodial agents essential infrastructure for scaling decentralized identity systems beyond early adopters to mainstream users who want the benefits of self-sovereign identity without the operational complexity of full self-custody. The ability to start with a custodial arrangement and later migrate to self-custody (or vice versa) provides a flexible adoption path that accommodates users at different points in their technical journey.
The custodial agent pattern exemplifies KERI's design philosophy of enabling real-world deployment scenarios while maintaining cryptographic verifiability and user sovereignty. By separating signing and rotation authorities through partial rotation, KERI provides the technical foundation for a new generation of identity services that are simultaneously user-friendly and truly self-sovereign.