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.

READY-MADE MIDDLEWARE FOR EXPRESS AND FLASK, PLUS THE AGENT-SIDE EXAMPLES.

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.",
  "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.

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.