Humanos SDK for TypeScript/JavaScript

Official TypeScript/JavaScript SDK for the Humanos API. Provides automatic request signing, webhook verification and decryption, and full API access for credential management.

Features

• Automatic Request Signing - All API requests are signed with HMAC-SHA256
• Webhook Verification - Verify signatures and decrypt encrypted payloads
• TypeScript Support - Full type definitions included
• Simple API - Clean interface for all Humanos endpoints

Getting Started

1. Create an Account

Sign up at humanos.id and create your organization.

2. Get Your API Keys

In the Humanos Dashboard, go to Settings > API Keys and copy:

• API Key - Used to authenticate requests
• Signature Secret - Used to sign requests with HMAC-SHA256

3. Get Your Webhook Keys

In the Humanos Dashboard, go to Settings > Webhooks and copy:

• Webhook Signature Secret - Used to verify incoming webhook signatures
• Webhook Encryption Secret - Used to decrypt webhook payloads
• Webhook Encryption Salt - Used alongside the encryption secret

4. Install the SDK

npm install @humanos-ai/sdk

5. Initialize the Client

import { HumanosClient } from "@humanos-ai/sdk";

const client = new HumanosClient({
  basePath: "https://api.humanos.id",
  apiKey: process.env.HUMANOS_API_KEY!,
  signatureSecret: process.env.HUMANOS_SIGNATURE_SECRET!,
});

6. Make Your First API Call

Fetch all your credential requests:

const response = await client.requests.getRequests();
console.log(response.data);

Usage Examples

Create a Credential Request

Send a credential request to one or more contacts using pre-configured resources:

const request = await client.requests.generate({
  contacts: ["[email protected]"],
  securityLevel: "CONTACT",
  resourcesIds: ["your-resource-id"],
});

console.log("Request ID:", request.data.id);
console.log("Credentials:", request.data.credentials);

You can also use group IDs to include all resources in a group:

const request = await client.requests.generate({
  contacts: ["[email protected]"],
  securityLevel: "CONTACT",
  groupIds: ["your-group-id"],
});

Or provide inline credential data directly:

const request = await client.requests.generate({
  contacts: ["[email protected]"],
  securityLevel: "CONTACT",
  credentials: [
    {
      scope: "onboarding",
      type: "JSON",
      name: "Service Agreement",
      data: [
        { label: "Company", type: "string", value: "Acme Corp" },
        { label: "Plan", type: "string", value: "Enterprise" },
      ],
    },
  ],
});

Receive Webhooks

Humanos sends webhook events when credentials are signed, identity checks complete, or OTPs fail. Payloads are encrypted and signed.

The SDK provides createWebhookHandler which handles signature verification and payload decryption automatically:

import express from "express";
import { createWebhookHandler, WebhookConfig } from "@humanos-ai/sdk";

const app = express();

// Use express.text() to preserve the raw body for signature verification
app.use(express.text({ type: "application/json" }));

const webhookConfig: WebhookConfig = {
  signatureSecret: process.env.HUMANOS_WEBHOOK_SIGNATURE_SECRET!,
  encryptionSecret: process.env.HUMANOS_WEBHOOK_ENCRYPTION_SECRET!,
  encryptionSalt: process.env.HUMANOS_WEBHOOK_ENCRYPTION_SALT!,
};

app.post(
  "/webhook",
  createWebhookHandler(webhookConfig, (payload) => {
    console.log("Event type:", payload.eventType);

    switch (payload.eventType) {
      case "credential":
        console.log("Credential signed:", payload.requestId);
        break;
      case "identity":
        console.log("Identity verified:", payload.requestId);
        break;
      case "otp.failed":
        console.log("OTP failed:", payload.requestId);
        break;
      case "test":
        console.log("Test event received");
        break;
    }
  }),
);

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});

For local development, use ngrok to expose your server:

ngrok http 3000

Then set the ngrok URL (e.g. https://xxxx.ngrok-free.app/webhook) as your webhook URL in the Humanos Dashboard under Settings > Webhooks.

API Reference

Resources

// List resources
const resources = await client.resources.getResources();

// List resource groups
const groups = await client.resources.getGroups();

// Download a credential file
const file = await client.resources.download(credentialId);

Requests

// List requests
const requests = await client.requests.getRequests();

// Get request details
const detail = await client.requests.getRequestDetail(requestId);

// Create a credential request
const request = await client.requests.generate({ ... });

// Cancel a request
await client.requests.cancelRequest(requestId);

// Resend OTP
await client.requests.resendOtp(requestId);

Users

// Create or update users
const users = await client.users.create([
  {
    contact: "[email protected]",
    internalId: "your-internal-id",
    identity: {
      fullName: "John Doe",
      birth: "1990-01-01",
      docId: "123456789",
      countryAlpha3: "USA",
    },
  },
]);

Error Handling

The SDK throws errors for failed requests. The error object includes the HTTP response when available:

try {
  const request = await client.requests.generate({ ... });
} catch (error) {
  if (error.response) {
    console.error('Status:', error.response.status);
    console.error('Body:', error.response.data);
  } else {
    console.error('Error:', error.message);
  }
}

Documentation

• API Documentation
• Humanos Website

Support

• Email: [email protected]

License

MIT License - see LICENSE file for details.