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 and adds full types:

• 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 16 or newer. The SDK sends its own API-Version header (currently 2026-09-01), which overrides your API key’s pinned version. 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: API Keys in the dashboard sidebar, for the API Key and Signature Secret.
2. Webhook credentials: Webhooks in the dashboard sidebar, for each endpoint’s 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 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 },
});

Other languages

Not on Node? The Authentication page documents the signing scheme for implementing a client in any language.