SDK Reference

Installation

npm install @humanauth/sdk

@humanauth/harp is no longer needed. Protocol types and crypto primitives are included in the SDK.

Non-TypeScript languages

Building in Python, Go, Java, Ruby, Rust, or another language? The HumanAuth Platform publishes an OpenAPI 3.1 specification you can use to codegen typed clients. See the OpenAPI Spec reference for example commands per language.

HumanAuthClient

The primary class for sending requests to humans and receiving responses.

Constructor

import { HumanAuthClient } from "@humanauth/sdk";

const client = HumanAuthClient.fromPairing(pairing);

Creates a client from a saved Pairing. The client handles encryption, relay communication, signature verification, and polling.

authorize(options)

Request binary approval. Blocks by default until the human responds or TTL expires.

const result = await client.authorize({
  action: "deploy_production",
  description: "Deploy API v2.1.0 to production",
  severity: "high",
  parameters: { service: "api", version: "2.1.0" },
  reasoning: "New features ready, all tests passing",
  ttl: 300,
});

if (result.decision === "approved") {
  await deploy();
} else {
  console.log(`Denied: ${result.reason}`);
}

AuthorizeOptions:

Field	Type	Required	Default	Description
action	string	Yes	—	Action identifier
description	string	Yes	—	Human-readable description
severity	Severity	No	”medium”	low, medium, high, critical
assurance	Assurance	No	”biometric”	tap, biometric, elevated
parameters	Record<string, unknown>	No	—	Action parameters for context
reasoning	string	No	—	Why the agent wants this
context	Record<string, unknown>	No	—	Cross-protocol references
ttl	number	No	300	Timeout in seconds (max 86400)
blocking	boolean	No	true	If false, returns request_id immediately
callbackUrl	string	No	—	Webhook URL for non-blocking
callbackSecret	string	No	—	HMAC secret for webhook

The per-request callbackUrl / callbackSecret pair is the original delivery model and remains supported. For tenant-level subscriptions with full delivery audit, retry semantics, and HMAC verification helpers, see the Webhook Subscriptions guide.

AuthorizeResult:

interface AuthorizeResult {
  decision: "approved" | "denied";
  reason?: string;
}

collect(options)

Request structured data input. Blocks by default.

const result = await client.collect({
  action: "deployment_config",
  description: "Please configure the deployment",
  schema: {
    fields: [
      {
        name: "target",
        type: "select",
        label: "Deploy Target",
        required: true,
        options: [
          { value: "staging", label: "Staging" },
          { value: "production", label: "Production" },
        ],
      },
      {
        name: "notify_team",
        type: "checkbox",
        label: "Notify team on Slack",
        default: true,
      },
    ],
  },
  severity: "medium",
  ttl: 600,
});

console.log(result.form_data);
// { target: "staging", notify_team: true }

CollectOptions:

Field	Type	Required	Default	Description
action	string	Yes	—	Action identifier
description	string	Yes	—	What data you need and why
schema	CollectSchema	Yes	—	Form definition (max 20 fields)
severity	Severity	No	”medium”	How sensitive is this data
assurance	Assurance	No	”biometric”	Authentication level
parameters	Record<string, unknown>	No	—	Additional context
reasoning	string	No	—	Why you need this data
context	Record<string, unknown>	No	—	Cross-protocol references
ttl	number	No	600	Timeout in seconds
blocking	boolean	No	true	If false, returns request_id immediately
callbackUrl	string	No	—	Webhook URL
callbackSecret	string	No	—	HMAC secret

CollectResult:

interface CollectResult {
  form_data: Record<string, unknown>;
  reason?: string;
}

CollectSchema:

interface CollectSchema {
  fields: CollectField[];    // max 20 fields
  submitLabel?: string;      // custom submit button text
}

interface CollectField {
  name: string;
  type: "select" | "multiselect" | "checkbox" | "number" | "datetime";
  label: string;
  description?: string;
  required?: boolean;
  default?: unknown;
  options?: { value: string; label: string }[];  // for select/multiselect
  min?: number;           // for number
  max?: number;           // for number
  step?: number;          // for number
  minDate?: string;       // for datetime (ISO 8601)
  maxDate?: string;       // for datetime (ISO 8601)
}

inform(options)

Send a notification. Always fire-and-forget — returns after relay acknowledges receipt.

await client.inform({
  action: "deploy_complete",
  description: "Deployment to staging completed successfully",
  severity: "low",
  category: "result",
});

InformOptions:

Field	Type	Required	Default	Description
action	string	Yes	—	Action name or context
description	string	Yes	—	Notification message
severity	Severity	No	”low”	Urgency level
category	string	No	”general”	escalation, result, status, error, general
parameters	Record<string, unknown>	No	—	Additional context
reasoning	string	No	—	Why you’re sending this
callbackUrl	string	No	—	Webhook fires on “viewed” state
callbackSecret	string	No	—	HMAC secret

Returns Promise<void>.

cancel(requestId)

Cancel a pending request.

await client.cancel("req_abc123");

Only works when the request is in pending state. Throws if already delivered/decided.

status(requestId)

Check the current status of a request.

const status = await client.status("req_abc123");
console.log(status);
// { request_id: "req_abc123", status: "viewed", created_at: 1712345678, delivered_at: 1712345680, viewed_at: 1712345690 }

RequestStatus:

interface RequestStatus {
  request_id: string;
  status: "pending" | "delivered" | "viewed" | "decided" | "expired" | "cancelled";
  created_at: number;
  delivered_at?: number;
  viewed_at?: number;
  decided_at?: number;
}

Types

Pairing

interface Pairing {
  pair_id: string;
  platform_id: string;
  platform_name: string;
  device_id: string;
  shared_secret: Uint8Array;
  encryption_key: Uint8Array;
  platform_auth_key: Uint8Array;
  app_auth_key: Uint8Array;
  signing_pub: Uint8Array;
  relay_url: string;
  paired_at: string;
}

Severity / Assurance

type Severity = "low" | "medium" | "high" | "critical";
type Assurance = "tap" | "biometric" | "elevated";

Pairing Management

loadPairing(pairId)

import { loadPairing } from "@humanauth/sdk";
const pairing = await loadPairing("pair_abc123");

listPairings()

import { listPairings } from "@humanauth/sdk";
const pairings = await listPairings();

Crypto Module

encrypt(key, plaintext)

import { encrypt } from "@humanauth/sdk";
const { nonce, ciphertext } = encrypt(encryptionKey, plaintextBytes);

decrypt(key, nonce, ciphertext)

import { decrypt } from "@humanauth/sdk";
const plaintext = decrypt(encryptionKey, nonce, ciphertext);

deriveSharedSecret(privateKey, publicKey)

import { deriveSharedSecret } from "@humanauth/sdk";
const sharedSecret = deriveSharedSecret(myPrivateKey, theirPublicKey);

deriveKeys(sharedSecret)

import { deriveKeys } from "@humanauth/sdk";
const { encryption_key, platform_auth_key, app_auth_key } = deriveKeys(sharedSecret);

Environment Variables

Variable	Default	Description
HumanAuth_PAIRINGS_DIR	~/.harp/pairings	Directory for saved pairing files
HumanAuth_AUDIT_DIR	~/.harp/audit	Directory for audit log files