Skip to main content

API Integration Tutorials

This guide walks through the end-to-end issuance and verification flows available in the Hovi API. We reference our TypeScript Examples Repository to demonstrate how to structure these requests in a real-world application.

Repository Access: All files referenced below can be found in the Hovi API 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-api-examples.git
    cd hovi-api-examples/typescript/api

  2. Install Dependencies: Install the necessary packages to run the scripts.

    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.

General Lifecycle​

Issuing a credential involves a specific sequence of steps to ensure trust and security. While protocols vary, the logical flow remains consistent.

  1. Configure Issuer (Setup): Before anything else, you must define who is issuing the credential (the Tenant) and what data structure they are issuing (the Credential Template).

  2. Establish Secure Connection (Ecosystem Dependent):

    • For Cheqd, Indicio, PrivadoID: You cannot just send data to a user; you must first establish a private, encrypted communication channel. The user scans a "Connection Invitation" QR code to link their wallet to your issuer.

  3. Offer Credential: The issuer generates a "Credential Offer." This is a digital package sent to the user (or presented as a QR code) saying, "I would like to give you this document."

  4. Receive Credential: The user reviews the offer in their digital wallet and accepts it. The credential is now cryptographically stored on their device.

  5. Verify Credential: To prove validity, the issuer (or a third-party verifier) sends a "Proof Request." The user selects the credential in their wallet and agrees to share the specific data requested.

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, whether it's government ID compliance or privacy-preserving age verification.

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

OpenID​

The OpenID flow utilizes the OID4VCI standard for immediate issuance.

Credential FormatDescriptionExample Code
SD-JWTSupports complex claims with selective disclosure capabilities.See example
mDocMobile-optimized credential format standardized by ISO.See example
JSON-LDStandard W3C credentials signed using JSON Web Signatures.See example

Cheqd​

Cheqd is built on the Cosmos SDK and is optimized for commercial identity models and payment rails.

Credential FormatDescriptionExample Code
JSON-LDStandard W3C credentials with Cheqd network anchoring.See example
AnoncredsPrivacy-preserving credentials supporting Zero-Knowledge Proofs (ZKP).See example

Indicio​

Indicio is built on Hyperledger Indy, offering a robust network frequently used for enterprise and government identity solutions.

Credential FormatDescriptionExample Code
AnoncredsPrivacy-preserving credentials supporting Zero-Knowledge Proofs (ZKP).See example
JSON-LDStandard W3C credentials with Indy network anchoring.See example

PrivadoID​

PrivadoID focuses on native integration of Zero-Knowledge identity and privacy-by-design principles.

Credential FormatDescriptionExample Code
JSON-LDW3C credentials optimized for the Privado ecosystem.See example

Contents