Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 144 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 service endpoint is a network address, typically expressed as a URL, that identifies the location where a service can be accessed and operations can be performed. In the KERI ecosystem, service endpoints are fundamental to the protocol's distributed architecture, enabling discovery and interaction with infrastructure components without requiring centralized registries.
Service endpoints follow standard URL conventions (e.g., http://witness-demo:5642/oobi/BBilc4...) and may include path components, query parameters, and port specifications. They represent the concrete network locations where KERI protocol messages can be sent and received.
Service endpoints are critical to KERI's decentralized architecture in several ways:
OOBI Integration: Service endpoints are the core component of Out-Of-Band Introductions (OOBI), which pair a URL with an AID to enable discovery. The OOBI principle "Discovery via URI, trust via KERI" means service endpoints handle discovery while KERI's cryptographic verification establishes trust. An OOBI like ("http://8.8.5.6:8080/oobi", "EaU6JR2nmwyZ...") associates a service endpoint with an identifier.
Witness and Watcher Infrastructure: Witnesses and watchers expose service endpoints for KEL publication and retrieval. Controllers configure witness endpoints during inception events, and these endpoints enable indirect mode operations where validators retrieve key event logs from witnesses rather than directly from controllers.
: In and implementations, service endpoints appear in DID Documents to advertise available services. The specification explicitly maps KERI witness endpoints to DID Document service entries with type "witness".
URL Structure: Service endpoints should follow standard URL conventions with scheme (http/https), host, port, and path components. Query parameters can provide metadata (name, role, tags) without affecting cryptographic verification.
Security Model: Service endpoints themselves are not trusted in KERI's security model. Discovery happens via URLs, but trust is established through subsequent cryptographic verification of KELs and signatures. This "discovery via URI, trust via KERI" principle means compromised or malicious endpoints cannot forge valid KERI events.
Network Accessibility: Service endpoints must be network-accessible to their intended audience. Witnesses typically require public endpoints, while agents may use private networks. Firewall configurations and network topology affect endpoint reachability.
Role-Based Endpoints: Different KERI roles (witness, watcher, mailbox, controller) may expose different endpoint paths or ports. The endpoint role determines available operations and expected message formats.
Well-Known URIs: Implementing /.well-known/keri/ paths enables standardized discovery patterns. This is particularly important for did:webs implementations where DID resolution depends on well-known locations.
Endpoint Rotation: When service endpoints change (new IP, different port), controllers must update their KELs through interaction or rotation events that include new endpoint seals. This ensures validators can discover current endpoints.
Multi-Tenant Considerations: Services like KERIA support multiple AIDs per instance, requiring endpoint design that can route requests to appropriate agents based on AID prefixes or other identifiers in the request path.
did:websAgent Communication: KERIA agents expose multiple service endpoints on separate interfaces: a Boot Interface for initialization, an Admin Interface for client operations, and a KERI Protocol Interface for external protocol interactions. This separation enables network-level security controls.
Role Authorization: Service endpoints are associated with specific roles (witness, watcher, mailbox, controller) through end roles, which are authorization records that grant an AID permission to serve in a particular capacity. The endpoint role determines what operations are available at that URL.
Discovery Mechanisms: Service endpoints enable multiple discovery patterns including well-known URIs (/.well-known/keri/oobi/), query-based resolution, and percolated discovery through witness networks. The flexibility of URL-based addressing allows KERI to leverage existing internet infrastructure while maintaining cryptographic security through subsequent verification.