Integrate AmHuman

Quick Start

Four steps to verify humans on your site. No backend code needed for most use cases.

iah_pk_a1b2c3d4e5f6...

npm install @amhumanorg/react

import { AmHumanVerify } from '@amhumanorg/react';

function Checkout() {
  const [verified, setVerified] = useState(false);

  return (
    <form onSubmit={handleSubmit}>
      {/* ... your form fields ... */}

      <AmHumanVerify
        clientKey="iah_pk_..."
        purpose="Complete purchase"
        onVerified={() => setVerified(true)}
      />

      <button type="submit" disabled={!verified}>
        Place Order
      </button>
    </form>
  );
}

yourdomain.com
staging.yourdomain.com
localhost  ← works automatically for dev

Installation

Packages are published on the public npm registry (@amhumanorg/*). Choose your framework — all wrap the same widget.

npm install @amhumanorg/react

Add the Widget

The widget renders a self-contained verification UI inside your page. The user types their AmHuman handle, approves on their device, and your callback fires. You don't need to manage any of the verification logic.

What the user sees

Props / Options

Callbacks

The widget communicates results through callbacks. At minimum, handle onVerified.

Backend Validation

For payments, limited inventory, or anything where a forged verification has real consequences, validate the token on your server before proceeding. This prevents users from faking the onVerified callback in dev tools.

Step 1: Pass the token to your backend

The onVerified callback includes a result.token — a one-time cryptographic proof. Send it to your server alongside your form data.

import { AmHumanVerify } from '@amhumanorg/react';

function Checkout({ orderData }) {
  async function handleVerified(result) {
    // Pass the token to your backend alongside order data
    const res = await fetch('/api/place-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        ...orderData,
        humanToken: result.token,
      }),
    });
    // ...
  }

  return (
    <AmHumanVerify
      clientKey="iah_pk_..."
      purpose="Purchase: 2x concert tickets"
      onVerified={handleVerified}
    />
  );
}

Step 2: Validate on your server

POST /api/verify/validate on your API host with your secret key in the X-API-Key header (same key as the vendor dashboard). Example base URL: https://amhuman-api.onrender.com — set NEXT_PUBLIC_API_URL in the web app to match. The token is single-use and expires after 5 minutes.

// In your order/checkout endpoint — use your API origin + POST /api/verify/validate
// Example origin: https://amhuman-api.onrender.com
app.post('/api/place-order', async (req, res) => {
  const { humanToken, ...orderData } = req.body;

  const verify = await fetch('https://amhuman-api.onrender.com/api/verify/validate', {
    method: 'POST',
    headers: {
      'X-API-Key': 'iah_sk_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ token: humanToken }),
  });

  const body = await verify.json();
  const valid = body?.data?.valid;

  if (!valid) {
    return res.status(403).json({ error: 'Human verification failed' });
  }

  await processOrder(orderData);
});

Validation response

Test Mode

Use your test frontend key (iah_pk_test_...) to test the full flow without real users. The widget works identically but uses reserved test handles that auto-respond.

AmHuman.verify({
  clientKey: 'iah_pk_test_...',   // Use your test key from the dashboard
  purpose: 'Test checkout',
  container: '#amhuman',
  onVerified: function(result) {
    console.log('Verified!', result);
    // result.token — validate server-side with POST /api/verify/validate + X-API-Key
  },
});

// Reserved test handles (type in the widget):
//   test_approve  → auto-confirms after ~2 seconds
//   test_deny     → auto-denies after ~2 seconds
//   test_expire   → never responds (times out)

Test handles

Verification Levels

Choose how much proof you need. Set a default in your dashboard, or override per-request.

Webhooks

Instead of (or in addition to) widget callbacks, receive real-time HTTP notifications on your server when a verification completes. Configure your webhook URL in the dashboard.

Payload

{
  "event": "verification.completed",
  "requestId": "req_abc123",
  "status": "confirmed",
  "handle": "@satvi",
  "purpose": "Concert ticket purchase",
  "verificationLevel": "ping",
  "verifiedAt": "2026-03-07T14:30:00Z"
}

Verifying signatures

Every webhook includes an X-AmHuman-Signature header. Verify it using your webhook secret (found in your dashboard) to ensure the request is authentic.

import crypto from 'crypto';

app.post('/webhook/amhuman', (req, res) => {
  const signature = req.headers['x-amhuman-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.AMHUMAN_WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  const { requestId, status, handle } = req.body;
  // Handle the event...

  res.status(200).send('OK');
});

Error Codes

Rate Limits

Rate limits are per-vendor and depend on your plan tier.