EarthID Web SDK

A lightweight SDK to easily integrate EarthID's web-based identity and document-sharing features into your web or JavaScript application.

Supports secure authentication, QR code generation, and real-time socket communication with the EarthID platform.

📦 Installation

Install via npm:

npm install earthid-web-sdk

🚀 Quick Start

import EarthIDSDK from 'earthid-web-sdk';

const sdk = new EarthIDSDK({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://stage-apiv2.myearth.id',
  socketUrl: 'https://stage-socketv2.myearth.id',
  debug: true  // Optional: Enable debug logging
});

📚 Table of Contents

• Installation
• Quick Start
• Initialization
• API Methods
  • getVendor
  • generateHash
  • generateQrCodeNest
  • listenForServiceProviderResponse
  • listenForUserData
  • disconnect
• QR Code Use Cases & Examples
• Typical Flow Sequence
• License

🛠 Initialization

Initialize the SDK using your EarthID credentials:

const sdk = new EarthIDSDK({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://stage-apiv2.myearth.id',
  socketUrl: 'https://stage-socketv2.myearth.id'
});

📡 Available Methods

1. getVendor()

Fetch vendor information using your vendor API key and a session ID.

const vendor = await sdk.getVendor('VENDOR_API_KEY', 'SESSION_ID');
console.log(vendor);

Returns vendor metadata including secretKey and apiKey.

2. generateHash()

Generate a secure HMAC SHA-256 hash for authentication.

const timestamp = Date.now();
const hash = sdk.getHash('VENDOR_SECRET_KEY', 'VENDOR_API_KEY', timestamp);

Parameters:

• vendorSecretKey (string)
• vendorApiKey (string)
• timestamp (number, optional)

3. generateQrCodeNest()

Generate a QR code for a specific request type using a hash.

const qrCode = await sdk.generateQrCodeNest(hash, 'VENDOR_API_KEY', timestamp, 'document');

4. listenForServiceProviderResponse()

Listen for service provider events via WebSocket:

sdk.listenForServiceProviderResponse((err, data) => {
  if (err) console.error(err);
  else console.log('Service Provider:', data);
});

5. listenForUserData()

Listen for user authentication data:

sdk.listenForUserData((err, data) => {
  if (err) console.error(err);
  else console.log('User Data:', data);
});

6. disconnect()

Disconnect from the WebSocket server:

sdk.disconnect();

📘 QR Code Use Cases & Examples

When calling generateQrCodeNest(), the requestType parameter determines the use case:

| Request Type | Description | |------------------|-----------------------------------------------------------------------------| | login | Initiate Passwordless(QR-based) login and wallet authentication | | document | Request for document access from wallet | | selectiveData | Selective Data Disclosure — request specific fields from user's document | | minAge | Request Proof of Age for ZKP for minimum age (e.g., 18+, 21+) | | ageRange | Request Proof of Age for a specific age range (e.g., 5-12, 18-35) | | balance | Request proof of minimum wallet balance | | idvProof | Request for ID Verification proof from the wallet |

Examples:

1. Passwordless Login flow

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'login');

2. Document request

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'document');

3. Selective Data Disclosure

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'selectiveData');

4. ZKP Minimum Age (e.g., 18+)

const zkpData = {
    "request": "minAge",
    "type": "date",
    "value": inputValue(i.e. 18, 21, etc.),
    "unit": "years"
}

const zkpDataString = JSON.stringify(zkpData);

const jsonStringWithSingleQuotes = zkpDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);

5. ZKP Age Range (e.g., 18-35)

const ageData = {
      request: "ageRange",
      type: "date",
      minValue: "13",
      maxValue: "16",
      unit: "years"
};

const ageDataString = JSON.stringify(ageData);

const jsonStringWithSingleQuotes = ageDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);

6. ZKP for Proof of Funds

const zkpData = {
    "request": "balance",
    "type": "number",
    "minimum": formDataJson.inputValue
}

const zkpDataString = JSON.stringify(zkpData);

const jsonStringWithSingleQuotes = zkpDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);

7. ID Verification Proof

const idvData = {
    "request": "idvProof",
    "company": "EarthID"
}

const idvDataString = JSON.stringify(idvData);

const jsonStringWithSingleQuotes = idvDataString.replace(/"/g, "'");

const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, jsonStringWithSingleQuotes);

🔁 Typical Flow Sequence (Example: Login)

Below is the typical sequence for initiating a secure login flow using the SDK:

// Step 1: Create SDK instance
const sdk = new EarthIDSDK({ apiKey, baseUrl, socketUrl });

// Step 2: Get vendor metadata
const vendor = await sdk.getVendor('VENDOR_API_KEY', 'SESSION_ID');

// Step 3: Generate a secure hash
const timestamp = Date.now();
const hash = sdk.getHash(vendor.values[0].secretKey, vendor.values[0].apiKey, timestamp);

// Step 4: Generate QR code for login (or any request type)
const qrCode = await sdk.generateQrCodeNest(hash, vendor.values[0].apiKey, timestamp, 'login');

// Step 5: Set up listeners to receive data in real-time
sdk.listenForServiceProviderResponse((err, data) => console.log('Service Provider:', data));
sdk.listenForUserData((err, data) => console.log('User Data:', data));

// Step 6: After receiving the user data process it for further verification or data handling as per the use case

Use the same sequence for any other request type — just change the last parameter in generateQrCodeNest() based on your use case.

🧪 Debug Mode

Enable debug logging by passing debug: true during initialization. Logs include socket connections, QR code responses, and internal status.

📦 Version

The SDK includes a static version:

console.log(EarthIDSDK.version); // "1.0.0"

📝 License

MIT License — Feel free to use, modify, and contribute.