HumanAuth in 5 Minutes

Get HumanAuth running end-to-end: a tenant and API key, an approver on your device, your agent asking for approval, and your resource server verifying the receipt — offline, against public keys. Five minutes of hands-on work, end to end. The one wait is tenant provisioning (a human does it — usually same-day): email us first, then do steps 2–3 while you wait, so the moment your key arrives you’re one command from your first receipt.

No tenant yet? Mint and verify a receipt in 60 seconds — offline

Verification is offline — no account needed. The CLI ships a fixture minter:

npx @humanauth/cli fixtures mint --action deployments:create --json > fix.json
jq .plan fix.json > plan.json && jq .jwks fix.json > jwks.json
npx @humanauth/cli verify "$(jq -r .jws fix.json)" \
  --audience ten_test --action deployments:create \
  --plan-file plan.json --jwks-file jwks.json

You just ran the exact check your resource server runs on every action: platform signature, device co-signature, plan-hash, expiry — no account, no network, nothing to trust.

Prerequisites

• Node.js 20+
• macOS 14+ on Apple Silicon to run the approver locally (the iPhone, iPad and Android apps are on the App Store and Google Play). No Mac? Everything else — SDK, CLI, verifier — is cross-platform: run the offline mint-and-verify loop above now, and have a Mac-owning teammate enroll as the approver, or self-host.
• An MCP-compatible agent (Claude Code, Cursor, …), a TypeScript project, or plain curl

1. Get a tenant

HumanAuth is in early access: pay-as-you-go tenants are provisioned by a human, usually within a day.

Request access, or book 20 minutes if you would rather talk it through first. Email support@humanauth.ai with the subject Tenant also works. Either way you’ll get back:

• a tenant_id and an API key (ha_…) for your agent
• your human_id (hu_…) rostered in the tenant

Prefer to run everything yourself? The verifier, SDK, CLI and MCP server are MIT-licensed on npm, and the platform can run in your own Cloudflare account under an Enterprise agreement — see the Self-Hosting Guide.

# Save the API key for the CLI and SDK
npx @humanauth/cli login        # prompts for the key, stores it in ~/.humanauth/config.json
npx @humanauth/cli status       # confirms tenant + key

2. Install an approver

1. Download the HumanAuth Approver for Mac from humanauth.ai/download (Developer-ID signed and notarized; SHA-256 sums published).
2. Open it — it lives in the menu bar.
3. Sign in with the same email your tenant rostered.
4. Enroll the device: a P-256 key is generated inside the Secure Enclave, gated by Touch ID. The private key is hardware-bound — it cannot be exported, and re-enrolling your biometrics invalidates it.

Phones

The iPhone and iPad approver is on the App Store and the Android approver is on Google Play. Phone keys are generated on-device and stored in the system keychain; approvals are gated by Face ID / Touch ID.

3. Send your first request

npx @humanauth/cli test hu_you --description "First HumanAuth request"

Your Mac approver shows the request — approve it with Touch ID. The CLI prints:

✓ APPROVED
  receipt_id: rct_9f2c…

The device signed the request’s plan hash — a canonical SHA-256 over the exact action and parameters — and the platform co-signed, producing a receipt neither party could have minted alone.

# Fetch the receipt JWS — this is what your resource server will verify:
RECEIPT_JWS=$(npx @humanauth/cli receipts get rct_9f2c… --json | jq -r .jws)

4. Wire up your agent

You’ve seen an approval land. Now put it in your agent’s hands:

MCP (zero-code)

Add HumanAuth to your MCP client config (Claude Code, Cursor, …):

{
  "mcpServers": {
    "humanauth": {
      "command": "npx",
      "args": ["@humanauth/mcp"],
      "env": { "HUMANAUTH_API_KEY": "ha_…" }
    }
  }
}

Your agent gains three tools: human_authorize, human_collect, human_inform.

MCP requests approval — it does not enforce

human_authorize asks a human and returns the decision to the agent as text — approve, deny, or expire, plus a receipt_id. That is a report, not a gate: it cannot stop an agent that skips the ask or ignores a denial. Real enforcement lives at the resource server that performs the irreversible action — mount @humanauth/verifier there, have the caller forward the receipt JWS to it, and refuse to act without a valid receipt (see step 5). Zero-code MCP is the request channel, not the gate.

TypeScript SDK

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

const auth = new HumanAuth({ apiKey: process.env.HUMANAUTH_API_KEY! });

const request = await auth.authorize("hu_you", {
  action: "deployments:create",
  description: "Deploy v2.1 to us-east-1",
  severity: "high",
});
const result = await request.wait();   // resolves when you decide

if (result.result === "approved") {
  const jws = await auth.receipts.getJws(result.receipt_id!);
  // Hand `jws` to the service performing the action; it verifies before acting.
}

Plain HTTP

curl https://api.humanauth.ai/v1/authorize \
  -H "Authorization: Bearer $HUMANAUTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"human_id": "hu_you",
       "action": "deployments:create",
       "description": "Deploy v2.1 to us-east-1",
       "severity": "high"}'
# → 202 { "request_id": "req_…", "plan_hash": "sha256:…", … }

The full surface is documented in the OpenAPI 3.1 spec.

5. Verify the receipt

This is the part that matters: your resource server — the service that executes the action — refuses to act without a valid receipt.

Verifier SDK

import { HumanAuthVerifier } from "@humanauth/verifier";
import { MemoryReplayStore } from "@humanauth/verifier/stores/memory";

const verifier = new HumanAuthVerifier({
  audience: "ten_yourtenant",
  jwksUri: "https://api.humanauth.ai/.well-known/jwks.json",
  replayStore: new MemoryReplayStore(),   // redis/postgres/sqlite stores available
});

const verified = await verifier.requireReceipt(receiptJws, {
  action: "deployments:create",
  plan: { description: "Deploy v2.1 to us-east-1", severity: "high" },
});
// Throws on: bad platform signature, bad device co-signature, wrong
// action, mutated plan, expired receipt, or replay. Otherwise: proceed.

CLI

# The plan is the exact action params you authorized — the verifier
# recomputes its hash and byte-compares it against the receipt.
echo '{"description":"Deploy v2.1 to us-east-1","severity":"high"}' > plan.json

npx @humanauth/cli verify "$RECEIPT_JWS" \
  --audience ten_yourtenant \
  --action deployments:create \
  --plan-file plan.json

Why offline verification matters

Verification needs only the published JWKS and the receipt itself. No call to HumanAuth, no dependency on our uptime — and the receipt stays verifiable even if we disappear. The device’s co-signature is checked against the public key embedded in the receipt, over the same plan-hash-bound bytes the platform signed.

Where next

• Integrator Cookbook — this same journey in Python, Java, and plain cURL, plus webhooks, audit export, and incident triage
• Use Cases & Patterns — quorums, batch approvals, CI/CD gates
• Verifier SDK guide — replay stores, Express & MCP middleware
• Webhook subscriptions — durable request.decided delivery
• Security model — keys, trust boundaries, and what we can’t do

Stuck, or want to talk it through?

If step 1 is the blocker, that is expected: tenants are set up by hand while the protocol settles. Request access and we will get you a tenant and an API key.

If you would rather ask questions than read further, book 20 minutes with the person who built it. Twenty minutes, no slides.