imnotahuman.ai
Play

Introduction

Quickstart

Add the widget to a page, verify the token on your server, and register a test agent in under ten minutes.

Two sides need setup: the website that asks for proof and the agent that provides it. You can test the website side alone with a test site key and the widget's Simulate agent button.

1. Create a site

Sign in with your email and password, then create a site with your domain, e.g. example.com. You receive two keys:

  • site_live_… for production. Challenges require a real agent proof.
  • site_test_… for development. Challenges can be completed with a simulated agent and tokens are marked mode: "test".

Site keys are public. A key only works from https://example.com, https://*.example.com and origins you add to allowed origins (add http://localhost:5173 for local work). See Origin binding.

2. Embed the widget

index.html
<form method="post" action="/checkout">
  <!-- The widget mounts right after this script tag and adds a hidden
       input named "imnotahuman-token"; it is filled once verified.
       Swap site_test_… for your site_live_… key before production.
       Test tokens fail server verification unless allow_test is true. -->
  <script src="https://imnotahuman.ai/widget.js"
          data-site-key="site_test_exampleweb2ab3cd4ef5gh6j"
          data-action="checkout"></script>
  <button type="submit">Continue</button>
</form>

With a test key the widget shows a Simulate agent button. Click it: the widget turns VERIFIED and fills the hidden input with a test token. Details, callbacks and the JavaScript API are on JavaScript.

3. Verify the token on your server

Never trust the widget state alone. Send the token to the API from your backend; no secret is needed.

curl
curl -X POST https://imnotahuman.ai/api/v1/tokens/verify \
  -H 'content-type: application/json' \
  -d '{"token":"<imnotahuman-token>","site_key":"site_test_exampleweb2ab3cd4ef5gh6j","consume":true,"allow_test":true}'

consume: true marks the token used so it cannot be replayed. Drop allow_test in production; test-mode tokens then fail with TOKEN_TEST_MODE. Full details: Server verification.

4. Register an agent (agent side)

In the dashboard, create an agent and generate a registration token (reg_…, valid 15 minutes, single use). Then, on the machine that will run the agent:

Terminal
curl -fsSL https://imnotahuman.ai/agent.mjs -o imnotahuman-agent.mjs
node imnotahuman-agent.mjs init --token reg_...
# ✓ Generated Ed25519 keypair
# ✓ Registered public key
# ✓ Proved possession of the private key
# ✓ Agent ID: agent_nova_8f2a
# ✓ Key ID: key_b7n2xq4mfc3rtw6y
# ✓ Private key saved to ~/.imnotahuman/agent.json (mode 600)

The private key is generated locally and never sent anywhere. Only the public key is uploaded. Needs Node 18+.

5. Complete a live challenge

Switch the widget to your site_live_… key. Open the widget's Details panel to copy the challenge URL, or read it from the page's <script type="application/json" data-imnotahuman-challenge> element, and let the agent sign it:

Terminal
node imnotahuman-agent.mjs verify https://imnotahuman.ai/c/ch_mfr4q2xk7tbn3ycz5w6ah2ep4d
# NOT HUMAN ✓
# Challenge  ch_mfr4q2xk7tbn3ycz5w6ah2ep4d
# Agent      Nova (agent_nova_8f2a)
# Method     ed25519_challenge
# Mode       live

The widget polls every two seconds and reports the verified state as soon as the proof is accepted.

Next steps