SDK (TypeScript/JavaScript)

The official Humanos SDK — automatic request signing, webhook verification and decryption, full type definitions

The official SDK for TypeScript and JavaScript is published on npm as humanos. It wraps every API call and removes the two fiddliest parts of a raw HTTP integration:

• Request signing — every call is signed automatically with your Signature Secret, so 401 Invalid signature disappears as a failure class.
• Webhook handling — verifies the x-signature/x-timestamp headers and decrypts the {iv, data, tag} payload envelope for you.
• Types — full TypeScript definitions for every request and response.

The HTTP API and the SDK are equivalent; everything in the API reference is available through both.

Installation

npm install humanos

Requires Node 18 or newer. Browser and edge/serverless runtimes are supported through a pluggable transport (below).

Configuration

You need two sets of credentials from the dashboard:

1. API credentials — Settings → API Keys: the API Key and Signature Secret.
2. Webhook credentials — Settings → Webhooks: the Webhook Signature Secret, Webhook Encryption Secret and Webhook Encryption Salt.

HUMANOS_API_KEY=<your-api-key>
HUMANOS_SIGNATURE_SECRET=<your-signature-secret>

HUMANOS_WEBHOOK_SIGNATURE_SECRET=<your-webhook-signature-secret>
HUMANOS_WEBHOOK_ENCRYPTION_SECRET=<your-webhook-encryption-secret>
HUMANOS_WEBHOOK_ENCRYPTION_SALT=<your-webhook-encryption-salt>

Everything else (action URNs, mandate URNs, request ids) is application data — keep it in code or your database, not in .env.

Quick start

import { HumanosClient } from "humanos";

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

// Sanity check — confirms the API key, signature secret, and signing handshake.
const { data } = await client.requests.list();
console.log(data);

A 200 OK with a (possibly empty) list means you’re wired up. From there, follow the guide that matches what you’re building — Collecting Approvals or Verifying Agent Actions — each shows the SDK calls alongside the raw HTTP.

Proxies and custom transports

All connection knobs are optional; omit them to connect directly:

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

  // Route through an explicit HTTP/HTTPS proxy (Node only) — CONNECT-tunneling
  // agents, so HTTPS APIs work behind corporate egress proxies.
  proxy: {
    host: "proxy.corp.internal",
    port: 8080,
    protocol: "http",
    auth: { username: "user", password: "pass" },
  },

  // Swap the HTTP transport: "fetch" for edge/serverless runtimes, "xhr" for
  // browsers, or your own adapter for tests. Requests are signed regardless
  // of the transport used.
  transport: "fetch",

  // Escape hatch for any other HTTP option; explicit keys above win.
  axiosConfig: { timeout: 10_000 },
});

Source and issues

The SDK is developed at github.com/Humanos-App/humanos-sdks — bug reports and feature requests are welcome there. Not on Node? The Authentication page documents the signing scheme for implementing a client in any language.