Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 14 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.
An end-role is an authorization mechanism in KERI that grants one AID (Autonomic Identifier) permission to serve in a specific role for another AID, establishing a cryptographically relationship between identifiers with defined permissions and responsibilities.
An end-role is a fundamental authorization data structure within the KERI (Key Event Receipt Infrastructure) protocol that establishes a formal, cryptographically verifiable relationship between two AIDs (Autonomic Identifiers). The term "end" in end-role signifies that this authorization exists at the "endpoints" of a relationship—between the authorizing AID and the authorized AID—rather than being mediated through a centralized authority.
End-roles serve multiple critical functions in the KERI ecosystem:
An end-role authorization consists of several key components:
Authorizing AID: The identifier that grants the role authorization. This is typically the principal or controller that owns the authority being delegated.
Authorized AID: The identifier that receives the role authorization. This is the agent, representative, or system that will act in the specified role.
Role Type: A string identifier specifying the nature of the authorization. Common role types include:
'agent': General agent authorization for operational tasks'mailbox': Authorization to act as a message mailbox'witness': Authorization to witness key eventsScope and Context: The boundaries within which the role authorization is valid, which may include:
Cryptographic Binding: The end-role authorization is anchored in the KEL (Key Event Log) of the authorizing AID, creating an immutable, verifiable record of the authorization.
While the KERI specification does not mandate a single canonical serialization format for end-role data, implementations typically use structured field maps that include:
cid (Controller Identifier): The AID prefix of the authorizing controller
EEr8A5QFqPnxh3aKLaOf0V4DUBNGS0xa8Hhav1uNJYSmeid (Endpoint Identifier): The AID prefix of the authorized endpoint/agent
ENYBj8F8aZnK7qWjChBVfwAUzfEnFrlrpAF0PIxXG2z1role: The role type being authorized
'agent', 'mailbox', 'witness'timestamp: When the authorization was created (optional)
'2024-01-15T10:30:00Z'End-role authorizations are typically encoded using one of KERI's standard serialization formats:
JSON Serialization: For human-readable representations and REST API interactions
{
"cid": "EEr8A5QFqPnxh3aKLaOf0V4DUBNGS0xa8Hhav1uNJYSm",
"eid": "ENYBj8F8aZnK7qWjChBVfwAUzfEnFrlrpAF0PIxXG2z1",
"role": "agent"
}
CESR Encoding: For compact binary representation in event streams
CBOR/MessagePack: For binary serialization in constrained environments
End-role data structures are intentionally compact:
Minimum Size: Approximately 100-150 bytes in JSON format, 60-80 bytes in CESR binary
Identifier Constraints:
cid and eid must be valid, fully-qualified KERI AIDsRole Type Constraints:
Validation Requirements:
cid) must have a valid, verifiable KELeid) must exist and be resolvableCreating an end-role authorization involves several steps that integrate with KERI's event-based architecture:
The controller of the authorizing AID constructs the end-role data structure with the required fields:
eid)The end-role authorization must be anchored in the authorizing AID's KEL through one of two event types:
Interaction Event: Most common approach for adding end-role authorizations
Rotation Event: Used when end-role changes coincide with key rotation
In the KERIA/Signify architecture, this is accomplished through API calls:
// Add an agent end role
await client.identifiers().addEndRole(
'myAidAlias', // Alias of authorizing AID
'agent', // Role type
agentAidPrefix, // AID prefix of authorized agent
timestamp // Optional timestamp
);
The client library handles:
For the end-role authorization to be considered stable and verifiable:
End-role authorizations can be modified through subsequent events:
Adding New Roles: Create additional interaction events with new end-role seals
Revoking Roles: Remove authorization by creating an event that explicitly revokes the role
Role Updates: Modify role parameters by revoking the old authorization and creating a new one
Verifying an end-role authorization requires validating multiple cryptographic and structural properties:
Validate the authorizing AID's KEL:
Locate the event that anchors the end-role authorization:
Extract and validate the end-role data:
eid) matches the claimed agentEnsure the authorization has not been revoked:
Validate the authorized AID itself:
In KERIA/Signify implementations, much of this verification is handled automatically by the agent and client libraries, but understanding the underlying process is critical for security-sensitive applications.
End-roles are utilized across multiple KERI-related protocols and specifications:
End-roles are a native KERI concept, integrated into the core protocol specification:
The KERIA (KERI Agent in the cloud) architecture makes extensive use of end-roles:
Agent Authorization Pattern: The most common use case in KERIA
Separation of Signing Authority: Critical security pattern
Example from KERIA setup:
// After creating a client AID, authorize the KERIA agent
const agentAid = await client.agent().pre(); // Get agent's AID
await client.identifiers().addEndRole(
clientAidAlias,
'agent',
agentAid
);
The IPEX protocol for credential exchange leverages end-roles:
The vLEI (verifiable Legal Entity Identifier) ecosystem uses end-roles extensively:
Organizational Role Credentials: End-roles support the issuance of role credentials
Delegation Chains: End-roles enable multi-level authorization
End-role authorizations have a well-defined lifecycle:
End-roles interact with and complement several other KERI data structures:
While end-roles and delegation are related, they serve different purposes:
Delegation: Creates a hierarchical relationship between AIDs
End-Role: Grants specific operational permissions
These can be combined: A delegated AID can have end-role authorizations, and an end-role authorized AID can be a delegator for other AIDs.
End-roles are closely related to ACDC credentials:
Role Credentials: ACDCs can represent role authorizations
Issuance Authorization: End-roles enable credential issuance
OOBIs are critical for end-role discovery and resolution:
Authorization Discovery: OOBIs enable finding end-role authorizations
Agent OOBIs: Special OOBI format for agent-authorized AIDs
http://agent-url/oobi/{cid}/agent/{eid}Example from KERIA:
const oobi = await client.oobis().get('myAidAlias', 'agent');
// Returns: http://keria:3902/oobi/EEr8A5Q.../agent/ENYBj8F...
Witnesses play a crucial role in end-role authorization:
Authorization Witnessing: End-role events must be witnessed
Mailbox Role: A specific end-role type for witnesses
End-roles introduce specific security considerations that implementers must address:
End-roles should grant the minimum necessary permissions:
Both authorizing and authorized AIDs require secure key management:
Relying parties must perform complete verification:
End-role revocations must be promptly propagated:
The most common end-role pattern in KERIA/Signify:
// 1. Initialize client and create AID
const client = new SignifyClient({url, bran});
await client.boot();
await client.connect();
const aid = await client.identifiers().create('myAlias', {
toad: 3,
wits: [wit1, wit2, wit3]
});
// 2. Get agent AID
const agentAid = await client.agent().pre();
// 3. Authorize agent
await client.identifiers().addEndRole(
'myAlias',
'agent',
agentAid
);
// 4. Generate OOBI for discovery
const oobi = await client.oobis().get('myAlias', 'agent');
// Share OOBI with parties that need to verify the agent relationship
Authorizing multiple agents for different purposes:
// Authorize different agents for different roles
await client.identifiers().addEndRole(
'myAlias',
'credential-issuer',
issuerAgentAid
);
await client.identifiers().addEndRole(
'myAlias',
'message-handler',
messageAgentAid
);
await client.identifiers().addEndRole(
'myAlias',
'witness-coordinator',
witnessAgentAid
);
Verifying an end-role authorization:
// 1. Resolve the authorizing AID's KEL
const oobi = `http://agent-url/oobi/${authorizingAid}/agent/${authorizedAid}`;
await client.oobis().resolve(oobi);
// 2. Get current key state
const keyState = await client.keyStates().get(authorizingAid);
// 3. Query for end-role authorization
const endRoles = await client.identifiers().getEndRoles(authorizingAid);
// 4. Verify the specific authorization exists
const hasAgentRole = endRoles.some(role =>
role.eid === authorizedAid && role.role === 'agent'
);
if (!hasAgentRole) {
throw new Error('Agent authorization not found or revoked');
}
Revoking an end-role authorization:
// Remove the end-role authorization
await client.identifiers().removeEndRole(
'myAlias',
'agent',
agentAid
);
// The removal is anchored in a new interaction event
// Witnesses will receipt the event
// Relying parties will detect the revocation when they refresh KEL state
End-roles are a fundamental authorization mechanism in KERI that enable flexible, secure delegation of operational capabilities between autonomous identifiers. By anchoring authorizations in cryptographically verifiable KELs, end-roles provide a decentralized alternative to traditional access control systems while maintaining strong security guarantees.
The end-role concept is particularly powerful in the KERIA/Signify architecture, where it enables the critical separation between signing authority (retained by the client) and operational management (delegated to the agent). This pattern allows KERI-based systems to achieve both security and usability, making decentralized identity practical for real-world applications.
Understanding end-roles is essential for anyone building KERI-based systems, particularly those involving agents, credentials, or organizational identity management. The combination of cryptographic verification, event-based lifecycle management, and flexible role definitions makes end-roles a versatile tool for implementing sophisticated authorization patterns in decentralized environments.
When implementing end-roles in KERIA/Signify systems:
Agent Authorization Timing: Always authorize the agent immediately after AID creation and before performing any operations that require agent involvement (credential issuance, witness coordination, etc.)
OOBI Generation: Generate and share agent OOBIs to enable other parties to discover and verify the agent relationship. The OOBI format http://agent-url/oobi/{cid}/agent/{eid} combines controller AID, role type, and agent AID for efficient resolution.
Asynchronous Operations: End-role authorization involves creating events that must be witnessed. Use the operation polling pattern (client.operations().wait()) to ensure the authorization is complete before proceeding.
Multiple Agents: A single AID can authorize multiple agents with different role types. Each authorization is independent and separately verifiable.
Principle of Least Privilege: Grant only the minimum necessary permissions through role types. Define narrow, specific roles rather than broad authorizations.
Regular Audits: Periodically review active end-role authorizations and revoke those no longer needed.
Verification Requirements: Always verify end-role authorizations by:
Key Protection: Both authorizing and authorized AIDs require secure key management. In KERIA/Signify, client keys remain at the edge and never leave the application, while agent keys are managed by the KERIA service.
Event Anchoring: End-role authorizations must be anchored in interaction or rotation events. The authorization data is sealed into the event, creating an immutable record.
Witness Confirmation: Ensure sufficient witness receipts are collected before considering the authorization stable. The TOAD threshold determines the minimum number of confirming witnesses.
Revocation Propagation: When revoking an authorization, ensure the revocation event is properly witnessed and published so relying parties can detect the change.
Standard Role Types: Use well-defined role type strings for common patterns ('agent', 'mailbox', 'witness') to ensure interoperability across implementations.
Custom Roles: When defining custom role types, document their semantics and ensure all parties in the ecosystem understand their meaning.
OOBI Discovery: Leverage OOBIs for end-role discovery. The agent OOBI format is standardized and should be used for agent authorizations.
Caching: Cache verified end-role authorizations to avoid repeated KEL resolution and verification. Implement cache invalidation based on KEL updates.
Batch Operations: When authorizing multiple agents or roles, consider batching the operations to reduce the number of events and witness interactions.
Lazy Resolution: Resolve and verify end-role authorizations only when needed, rather than eagerly resolving all possible authorizations.
Authorization Failures: Handle cases where end-role authorization fails due to:
Graceful Degradation: Design systems to handle authorization verification failures gracefully, with appropriate fallback behaviors.
Audit Logging: Log all end-role operations (creation, verification, revocation) for security auditing and troubleshooting.