A simple SDK for interacting with EarthID's web features
npm install earthid-web-sdkA 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.
---
Install via npm:
``bash`
npm install earthid-web-sdk
---
`js
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
});
`
---
- Installation
- Quick Start
- Initialization
- API Methods
- getVendor
- generateHash
- generateQrCodeNest
- listenForServiceProviderResponse
- listenForUserData
- disconnect
- QR Code Use Cases & Examples
- Typical Flow Sequence
- License
---
Initialize the SDK using your EarthID credentials:
`js`
const sdk = new EarthIDSDK({
apiKey: 'YOUR_API_KEY',
baseUrl: 'https://stage-apiv2.myearth.id',
socketUrl: 'https://stage-socketv2.myearth.id'
});
---
Fetch vendor information using your vendor API key and a session ID.
`js`
const vendor = await sdk.getVendor('VENDOR_API_KEY', 'SESSION_ID');
console.log(vendor);
Returns vendor metadata including secretKey and apiKey.
---
Generate a secure HMAC SHA-256 hash for authentication.
`js`
const timestamp = Date.now();
const hash = sdk.getHash('VENDOR_SECRET_KEY', 'VENDOR_API_KEY', timestamp);
Parameters:
- vendorSecretKey (string)
- vendorApiKey (string)
- timestamp (number, optional)
---
Generate a QR code for a specific request type using a hash.
`js`
const qrCode = await sdk.generateQrCodeNest(hash, 'VENDOR_API_KEY', timestamp, 'document');
---
Listen for service provider events via WebSocket:
`js`
sdk.listenForServiceProviderResponse((err, data) => {
if (err) console.error(err);
else console.log('Service Provider:', data);
});
---
Listen for user authentication data:
`js`
sdk.listenForUserData((err, data) => {
if (err) console.error(err);
else console.log('User Data:', data);
});
---
Disconnect from the WebSocket server:
`js`
sdk.disconnect();
---
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
`js`
const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'login');
2. Document request
`js`
const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'document');
3. Selective Data Disclosure
`js`
const qr = await sdk.generateQrCodeNest(hash, apiKey, timestamp, 'selectiveData');
4. ZKP Minimum Age (e.g., 18+)
`js
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)
`js
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
`js
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
`js
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);
`
---
Below is the typical sequence for initiating a secure login flow using the SDK:
`js
// 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.
---
Enable debug logging by passing debug: true during initialization. Logs include socket connections, QR code responses, and internal status.
---
The SDK includes a static version:
`js``
console.log(EarthIDSDK.version); // "1.0.0"
---
MIT License — Feel free to use, modify, and contribute.