# FAQ

**What does Heedeo do?**
It identifies every agent on your site and lets you decide who gets in and what they can do. Per route, it verifies the agent, identifies who it acts for, counts per principal and applies your rule: allow, challenge, throttle or block. See https://heedeo.com/docs/how-it-works.md.

**How is that different from a bot blocker or a CAPTCHA?**
It doesn't try to keep agents out. Agents that bring real customers get through. It asks agents to show who built them (a signature) and who they act for (a principal), and it limits the person, not the IP. People never see a puzzle. The only thing a person sees is one passkey confirmation, when an unknown agent signs up on their behalf.

**Which agents can be verified?**
Agents that sign with Web Bot Auth, from an operator on your `trustedOperators` list. Known signers today include ChatGPT agent, Goose, Browserbase and Anchor Browser, per https://blog.cloudflare.com/signed-agents/. The demo policy trusts `chatgpt.com`, `browserbase.com` and `anchorbrowser.io`.

**What is a "detected" agent?**
One recognised by its user agent but not signed (or signed by an untrusted operator). Rules treat it as unknown.

**Can an agent fake being ChatGPT?**
It can fake the user agent string, which makes it detected at most. It can't fake the signature: only a valid Ed25519 signature checked against a key in the operator's `/.well-known/http-message-signatures-directory`, from a trusted operator, makes an agent verified.

**Why isn't a valid signature enough?**
Anyone can publish a key directory on a domain they own and sign with it. So verified also needs the operator to be on your trusted list. A valid signature from anyone else is "Signed, untrusted" and counts as unknown.

**Who is the principal?**
The person or company the agent acts for. From a signed principal token when present (for example Skyfire KYAPay or Visa Trusted Agent Protocol). Otherwise, whoever finishes the passkey handoff. After signup, your own user ID.

**Does a passkey stop one person making many accounts?**
Not on its own. A passkey proves a real person finished the step, not a unique human: one person can hold several passkeys. Linking one person's several accounts relies on signed principal tokens when present, plus your own signals (payment card, verified email domain, device), set up at onboarding.

**Why per principal and not per IP?**
IPs are cheap to rotate. A farm behind 40 IPs that resolves to one principal gets one set of limits.

**What does throttle mean?**
Rate-limited, not refused: HTTP 429 with `Retry-After`. On the demo `/signup`, the 6th to 10th signups a day for one principal are limited to 1 an hour. From the 11th, block (403).

**Does my traffic leave my servers?**
Decisions run in your middleware. Only decision metadata (route, verdict, agent, reason, rule line) goes to the dashboard. Never request bodies, and reasons never contain principal identifiers. You can turn it off. See https://heedeo.com/docs/security.md.

**What if an operator's key directory is down?**
The request is treated as unsigned, so the agent is unknown. It is never treated as verified.

**Where are the per-principal counters kept?**
Where they live in your deployment, and whether a counter outage fails open or closed, are agreed during onboarding.

**Which frameworks are supported?**
Next.js middleware today. Express, Hono and Cloudflare Workers on request.

**Is it on npm?**
Not on public npm. Access to the package is provided at onboarding.

**How do I get access?**
Book a short call at https://cal.com/heedeo/30min, or have your agent `POST https://heedeo.com/api/book` for you. After the call the team gives you access to the package and sets up your first rules with you.

**Can I try the engine before a call?**
Yes. `/api/decide` runs the real policy engine on a demo policy, and `/api/visitor` really verifies signatures. See https://heedeo.com/docs/api.md.

**Who is behind Heedeo?**
Heedeo is backed by Entrepreneurs First (https://www.joinef.com).

**How can I check what you say here?**
https://heedeo.com/trust.md lists each checkable claim with the curl to check it.

---

Docs index: https://heedeo.com/docs.md. How to verify our claims: https://heedeo.com/trust.md. Book a call: https://cal.com/heedeo/30min

Updated: 2026-10-02