SDK Integration Tutorials

This guide walks through the end-to-end issuance and verification flows available in the Hovi SDK. We reference our SDK Examples Repository to demonstrate how to use the @hovi/core-sdk package to simplify your integration.

Repository Access: All files referenced below can be found in the Hovi SDK Examples Repository.

---

Project Setup

Follow these steps to get the example project running on your local machine.

1. Clone the Repository: Download the code to your local machine using git.

   git clone https://github.com/hovi-id/hovi-sdk-examples.git
   cd hovi-sdk-examples/tree/main/typescript/sdk

2. Install Dependencies: Install the necessary packages, including the Hovi Core SDK.

   npm install

3. Configure Environment: Create a .env file by copying the provided example. Open it and add your API_KEY and the Hovi BASE_URL (e.g., https://api.hovi.id).

   cp .env.example .env

4. Explore Shared Utilities: To keep our code clean and DRY (Don't Repeat Yourself), we use a centralized utils folder for common actions.

   • utils/tenant.ts: Handles the creation of the Tenant (Issuer).

---

General Lifecycle

The SDK simplifies the credential lifecycle by using Ecosystem Clients. You instantiate a client once, and it automatically handles authentication, request formatting, and ecosystem-specific nuances for you.

1. Initialize Client: Instantiate the specific client (e.g., OpenIdEcosystem, CheqdEcosystem) with your config. This is your main gateway to the Hovi platform.

2. Configure Issuer (Setup): Use the client to create a Tenant. This establishes the digital identity that will be issuing the credentials.

3. Establish Secure Connection (Ecosystem Dependent):

   • For Cheqd, Indicio, PrivadoID: You must establish a connection. The SDK provides helper methods to generate invitations and poll for completion status.

4. Offer Credential: The issuer uses the client to send a credential offer. The SDK formats this request according to the specific standards of the chosen ecosystem.

5. Receive Credential: The user accepts the offer in their wallet.

6. Verify Credential: The issuer uses the client to request a proof, and the user shares the requested data.

---

Supported Ecosystems

Hovi is built on open standards to ensure your credentials work across different networks and wallets. We support a wide range of credential formats—including mDocs, SD-JWT, AnonCreds, and JSON-LD—allowing you to choose the right standard for your specific use case.

For a deep dive into how these standards work together, visit our Interoperability Guide.

OpenID

The OpenID flow utilizes the OID4VCI standard. The SDK methods automatically generate the QR code URI needed for the user to claim the credential.

Credential Format	Description	Example Code
SD-JWT	Supports complex claims with selective disclosure capabilities.	See example
mDoc	Mobile-optimized credential format standardized by ISO.	See example
JSON-LD	Standard W3C credentials signed using JSON Web Signatures.	See example

Cheqd

The CheqdEcosystem client provides optimized methods for the Cheqd network, handling both Anoncreds and JSON-LD formats.

Credential Format	Description	Example Code
JSON-LD	Standard W3C credentials with Cheqd network anchoring.	See example
Anoncreds	Privacy-preserving credentials supporting Zero-Knowledge Proofs (ZKP).	See example

Indicio

The IndicioEcosystem client is designed for the Hyperledger Indy network, focusing on robust Anoncreds issuance and verification.

Credential Format	Description	Example Code
Anoncreds	Privacy-preserving credentials supporting Zero-Knowledge Proofs (ZKP).	See example
JSON-LD	Standard W3C credentials with Indy network anchoring.	See example

PrivadoID

The PrivadoEcosystem client handles the specific JSON-LD signature requirements and zero-knowledge features of the Privado network.

Credential Format	Description	Example Code
JSON-LD	W3C credentials optimized for the Privado ecosystem.	See example