Verifying an agent, for sites

How an agent identifies itself

When an agent calls your site, it sends two headers:

X-AgentID: AID-2032-A71F3C
Authorization: Bearer ak_live_<the agent's secret key>

You look up the first (public), and use it together with the second to call the proof endpoint below. Requests with neither header are just ordinary, unidentified visitors — nothing to check, nothing blocked. There's no "are you human or an agent" screen anywhere in this flow; the credential does the talking.

Fastest way in — one command that detects your project and wires the middleware in for you, in under a minute:

Open a terminal in your website project's own folder first — the one that already has your server's code in it (look for a package.json, or a requirements.txt / manage.py for Python). Running it anywhere else won't find anything to wire up.

npx --package=https://vagentid.com/downloads/agentid-init.tgz agentid-init

DETECTS NODE.JS AUTOMATICALLY AND OFFERS TO ADD THE ONE LINE FOR YOU (ASKING FIRST). FOR PYTHON, IT DROPS THE FILE IN AND SHOWS THE TWO LINES TO ADD. IT NEVER TOUCHES ANYTHING OUTSIDE THE FOLDER YOU RUN IT IN.

Want to go further and turn away bots entirely? The installer can also switch on strict mode — it blocks any request that identifies itself as a bot or script (curl, scrapers, headless browsers) unless it presents a verified AgentID certificate. It's a prompt during setup, so you don't need to touch any code.

ORDINARY BROWSERS ARE NEVER AFFECTED, WITH OR WITHOUT STRICT MODE. KNOWN SEARCH-ENGINE CRAWLERS AND UPTIME MONITORS (GOOGLEBOT, BINGBOT, UPTIMEROBOT, AND SIMILAR) ARE STILL LET THROUGH EVEN WHEN IT'S ON. YOU CAN TURN IT ON LATER TOO — JUST PASS { STRICT: TRUE } TO THE MIDDLEWARE.

Prefer to install it by hand?

READY-MADE MIDDLEWARE FOR EXPRESS AND FLASK, PLUS THE AGENT-SIDE EXAMPLES. INCLUDES STRICT MODE — SEE THE README.

Public lookup (no credentials needed)

Confirms whether a certificate exists and its current status. Anyone can call this — it's the same data shown on the public certificate page.

GET https://vagentid.com/api/v1/verify/AID-2032-A71F3C

200 OK
{
  "id": "AID-2032-A71F3C",
  "status": "active",
  "owner_display_name": "Max R.",
  "managed_by": null,
  "name": "Shopping agent",
  "permissions": {
    "purchase_limit": 100,
    "purchase_currency": "GBP",
    "read_email": true,
    "money_transfer": false,
    "custom": null
  },
  "issued_at": "2026-09-15T00:00:00.000Z",
  "expires_at": "2026-12-14T00:00:00.000Z"
}

RATE LIMITED. RETURNS 404 IF THE ID DOES NOT EXIST.

owner_display_name is who the certificate actually belongs to — the client, when an AgentID Partner registered this agent on their behalf. managed_by is that partner's company name in that case, otherwise null.

Proof of possession (stronger check)

A public ID alone can be copied by anyone. If you need proof the caller actually controls this agent's credentials — not just that it knows the public ID — have the agent forward its secret key with the request.

POST https://vagentid.com/api/v1/verify/AID-2032-A71F3C/prove
Authorization: Bearer ak_live_<the agent's secret key>

200 OK  { ...same fields as above..., "proof": true }
401 Unauthorized  { "error": "Key does not match this agent." }

MORE STRICTLY RATE LIMITED THAN THE PUBLIC LOOKUP.

Limitations, plainly

AgentID confirms identity and the owner's declared permissions at the time of the check. It does not enforce those permissions, does not sit inside your transaction, and is not a party to it. Treat a certificate as one input to your own risk decision, not as a guarantee.