> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://www.npmjs.com/package/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](/api-reference/latest) is available through both.

## Installation

```bash theme={"dark"}
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**.

```env theme={"dark"}
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

```typescript theme={"dark"}
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](/essentials/guides/collecting-approvals) or [Verifying Agent Actions](/essentials/guides/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:

```typescript theme={"dark"}
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](https://github.com/Humanos-App/humanos-sdks) — bug reports and feature requests are welcome there. Not on Node? The [Authentication](/essentials/authentication) page documents the signing scheme for implementing a client in any language.