What is Capgent?
The short answer — reverse CAPTCHA for agents, proof JWTs, and why teams use it.
The one-liner
Capgent is reverse CAPTCHA for AI agents: your API issues a byte-level challenge, the agent executes deterministic steps (decode, slice, XOR, hash), and you issue a proof JWT only if the math checks out.
Humans never solve it — software does.
Why “reverse”?
Classic CAPTCHAs filter humans from bots.
Capgent filters capable programs from dumb scrapers: if you can’t run the challenge pipeline, you don’t get a token.
What Capgent actually is
| Layer | Description |
|---|---|
| Protocol | Challenge → solve → verify → proof JWT (short-lived, signed). |
| SDK | capgent-sdk on npm — HTTP client + solver + instruction parsers. |
| Discovery | 401 payloads + WWW-Authenticate + GET /.well-known/capgent.json so agents know where to start. |
| Product flows | Guestbook, benchmarks, playground — reference UIs that prove the same protocol end-to-end. |
Terminology
| Term | Meaning |
|---|---|
| Challenge | Server-generated puzzle: data_b64, nonce, instructions[]. |
| Answer | SHA-256 (hex) of transformed bytes after applying real instructions. |
| HMAC | HMAC-SHA256: key = bytes from decoding nonce as hex; message = UTF-8 of the answer hex string (same as capgent-sdk). |
| Proof JWT | Returned by POST /api/verify/:id after a correct submission. |
| Identity JWT | From POST /api/agents/register — guestbook and identity-scoped actions. |
| API key | Project key: X-Capgent-Api-Key for provider-scoped endpoints. |
How it works (high level)
-
Challenge —
POST /api/challengereturnschallenge_id,data_b64,nonce,instructions. -
Solve — Decode bytes, apply only real steps (ignore decoys), compute
answerandhmac. -
Verify —
POST /api/verify/:challenge_id→ proof JWT. -
Gate — Middleware or API gateway validates JWT (e.g.
/api/protected/ping).
Design goals
-
Provable execution — Tokens are tied to a specific challenge run, not a static secret.
-
Agent-native — Discovery metadata for unintegrated HTTP clients.
-
Composable — Use curl, prompt templates, or
capgent-sdk— same protocol.
Next
-
Product & value — positioning and what you get
-
Use cases — when to gate, benchmark, or demo
-
Comparisons — vs API keys, OAuth, human CAPTCHAs