Everything you need to
verify humans.

curl -X POST https://humaverify.com/api/v1/verify \
  -H "Authorization: Bearer huma_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_abc123"}'

{
  "human": true,
  "confidence": 0.92,
  "token": "h_verified_Kd3mP8luYMC2Mi1x",
  "pii_stored": false,
  "agent": {                       // Pro & Enterprise
    "is_agent": false,
    "agent_confidence": 0,
    "signals": []
  }
}

// After a successful verify():
const result = await Huma.verify('user_123', 'huma_live_...');

if (result.human) {
  Huma.startSession('user_123', 'huma_live_...', result.token, {
    intervalMs: 30000, // every 30 seconds
    onAnomaly: function(r) {
      if (r.action === 'block') {
        window.location.href = '/logout'; // account takeover detected
      }
    }
  });
}

import { useHumaSession } from 'usehuma/react';

const { anomaly, lastResult } = useHumaSession({
  apiKey: 'huma_live_...',
  userId: 'user_123',
  token: verifyResult.token,
  onAnomaly: (r) => router.push('/logout'),
});

{
  "id": "wh_abc123...",
  "secret": "huma_whsec_abc123...",  // shown once
  "url": "https://yourdomain.com/webhooks/huma",
  "events": ["bot.detected", "human.verified"],
  "active": true
}

Huma-Signature: t=1716840000,v1=abc123def456...

import crypto from 'crypto';

function verifyWebhook(rawBody, signature, secret) {
  const [tPart, vPart] = signature.split(',');
  const timestamp = tPart.replace('t=', '');
  const received  = vPart.replace('v1=', '');

  const payload  = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

{
  "event": "bot.detected",
  "user_id": "user_123",
  "human": false,
  "confidence": 0.18,
  "score": 18,
  "token": "h_verified_Kd3mP8luYMC2Mi1x",
  "timestamp": "2026-05-25T21:00:00.000Z"
}

{
  "challenge_id": "ch_abc123...",
  "type": "click_targets",        // or "pattern"
  "payload": {
    "instruction": "Click the 🎯",
    "targets": [
      { "id": "t0", "x": 20, "y": 25, "label": "🌿" },
      { "id": "t1", "x": 65, "y": 25, "label": "🎯" },
      ...
    ]
  },
  "expires_in_seconds": 300
}

{ "passed": true, "token": "h_challenge_abc..." }

{ "passed": false, "message": "Incorrect answer", "attempts_remaining": 2 }

import { HumaChallenge } from 'usehuma/react';

// After verify() returns borderline confidence:
const ch = await fetch('/api/v1/challenge/create', {
  method: 'POST',
  headers: { Authorization: 'Bearer huma_live_...' },
  body: JSON.stringify({ userId }),
}).then(r => r.json());

return (
  <HumaChallenge
    challengeId={ch.challenge_id}
    type={ch.type}
    payload={ch.payload}
    apiKey="huma_live_..."
    onPassed={(token) => continueLogin(token)}
    onBlocked={() => router.push('/blocked')}
  />
);

import { verify } from "usehuma";

// Collects behavioral signals from the DOM and verifies in one call.
// Call this client-side at a critical moment (login, signup, checkout).
const result = await verify({
  apiKey: "huma_live_...",
  userId: "user_123",
});

if (result.human && result.confidence > 0.7) {
  // ✅ Real human — send result.token to your server for audit
} else {
  // 🚫 Bot — block or trigger step-up challenge
}

import { verifyWithSignals } from "usehuma";

// Browser: collect signals and forward them.
// const signals = Huma.debug()?.features;
// fetch('/api/check', { body: JSON.stringify({ userId, signals }) });

// In your API route (server-side):
const result = await verifyWithSignals({
  apiKey:   process.env.HUMA_API_KEY!,   // huma_live_... (keep secret)
  userId:   req.body.userId,
  signals:  req.body.signals,            // forwarded from browser
});

if (result.human) { /* allow */ }

import { useHuma } from "usehuma/react";

function SignupForm() {
  const { verify, collecting } = useHuma({
    apiKey: "huma_live_...",
    userId: currentUser.id,
  });

  async function handleSubmit() {
    const result = await verify();
    if (result.human) {
      // proceed
    }
  }

  return <button onClick={handleSubmit}>Sign up</button>;
}

import { HumaGate } from "usehuma/react";

// Wraps any form — silently verifies on submit.
// Shows HumaChallenge automatically if confidence is uncertain.
<HumaGate
  apiKey="huma_live_..."
  userId={user.id}
  onPass={(result) => submitForm(result.token)}
  onBlock={() => showBotError()}
>
  <MyForm />
</HumaGate>

import { useHumaSession } from "usehuma/react";

// Call after successful verify() to keep watching mid-session.
useHumaSession({
  apiKey:  "huma_live_...",
  userId:  user.id,
  interval: 45_000,                   // heartbeat every 45s
  onAnomaly: (action) => {
    if (action === "block") logout();  // account takeover detected
    if (action === "flag")  reVerify();
  },
});

// Bot-check a form inside a Server Action
"use server";
import { humaFormCheck } from "usehuma/next";

export async function signUp(formData: FormData) {
  const check = await humaFormCheck(formData); // uses HUMA_API_KEY env
  if (!check.human) redirect("/signup?error=bot_detected");
  // ...create the account
}

// Protect a Route Handler
import { withHumaProtection } from "usehuma/next";

export const POST = withHumaProtection(async (req, huma) => {
  const body = await req.json();   // handler still gets the body
  return Response.json({ ok: true, confidence: huma.confidence });
});

import type { VerifyResult, SessionResult } from "usehuma";

// VerifyResult
// { human: boolean; confidence: number; score: number;
//   token: string; pii_stored: false }

// SessionResult
// { score: number; delta: number; anomaly: boolean;
//   action: "allow" | "flag" | "block"; notes: string[] }