Verigrant
Get started

Verigrant › Guide for agent developers

Use Verigrant from your agent

Your agent can apply for a person, act for them at websites with a pass, propose tasks they approve, drop orders and read booking updates. This page lists the pieces and the order to use them in. The integration guide covers applying.

1. The pieces

  • The agent kit vg-agent-kit in Rust, and @verigrant/agent-kit for Node 20 or later with no dependencies. Both make Web Bot Auth signatures, attach the Verigrant-Pass header, call Verigrant, and talk to a site's door for agents. The TypeScript kit also carries the agent ID: the renewal, the level one exchange, clear actions, the change feed and the front's MCP endpoint.
  • The agent ID and the verigrant CLI An agent that acts without a person, or wants a site to know who operates it, carries a Verigrant agent ID. verigrant agent register gets one in two minutes. The guide for agent operators is the order to do it in.
  • The local MCP server vg-agent-mcp runs on the person's own device over standard input and output, so any MCP client can use Verigrant. init makes the keys, pair keeps the assistant code, and serve serves MCP.
  • The egress specification docs/agent-egress-pass-spec.md, "Obtaining a pass and attaching it at egress". It gives the call, the arguments, the result, the headers and a worked example that the kit's own tests check.

None of these is on a public registry yet. Write to support@verigrant.com to get them.

2. Pairing

  1. Make your keys. Run vg-agent-mcp init --state DIR --agent-url URL. It prints two public keys for the person, and a Web Bot Auth key directory to publish at your agent URL.
  2. The person pairs you. They paste the two keys in Verigrant, under Settings, Agents and approvals, and set your limits: sites, purposes, actions, how long a pass lasts and how many a day.
  3. Keep the assistant code. Verigrant shows them an assistant code once. Run vg-agent-mcp pair --state DIR. It reads the code from standard input, so the code never lands in your shell history.

A paired agent holds its own keys and the key to the one section of the person's record they chose. Keep them the way you keep any secret.

3. Getting and using a pass

Ask for a pass with one MCP tools/call of get_agent_pass to POST https://verigrant.com/api/agent/mcp. Sign every request afresh with the request key the person's mandate names, in three headers: X-Verigrant-Vera-Id, X-Verigrant-Agent-Timestamp and X-Verigrant-Agent-Signature.

  • Arguments site, purpose and agent_key_thumbprint, and if you need them actions, ttl_seconds from 60 to 600, and plan_id with plan_step. No argument names a person, and every argument can only narrow what the person allowed.
  • The result The pass, how to present it, the person's address at that site, what Verigrant observed about the person, and when the pass ends.
  • Attaching it Send it as the Verigrant-Pass header inside a Web Bot Auth signature (RFC 9421), signed with the key whose thumbprint you gave, to that site and its subdomains only.
  • How the site checks it Offline, against https://verigrant.com/api/.well-known/verigrant-pass-keys.json. The site never calls Verigrant, and Verigrant never sees your request, the page or the response.

Two keys, kept apart

The request key signs requests to Verigrant and nothing else. The Web Bot Auth key signs requests to websites. Keeping them apart stops a site from linking the person across sites.

4. The tools on Verigrant's face for the person's agent

  • get_agent_pass A pass for one site.
  • propose_task_plan and get_plan_pay_grant A chain of steps for the person to approve, and the payment approval for a step that buys.
  • record_service_outcome Report what a site's door answered.
  • get_traveler_details, drop_order and order_status The person's traveller details sealed to the business, the order, and the business's signed outcome.
  • register_update_key and booking_updates The updates a business sends about a booking, when the person allows it.
  • list_inbox and read_inbox_item The person's inbox.

Applying for the person works as before, with POST https://verigrant.com/api/vera/applications. The integration guide and llms.txt have it.

5. Rules your agent keeps

  • Never log a pass And never send it anywhere but its own site.
  • Get a new pass before the old one ends Short passes are how revoking reaches a site.
  • A refusal is an answer Do not retry with other arguments. Tell the person what it said.
  • Ask the person for a step up On step_up_required, tell the person which approval the step needs, wait until they say they gave it, then ask again. Nothing your agent sends can approve a step.
  • Ask for what you need next Request the actions the next requests need, and no more.

6. What is not live yet

  • Money A payment approval carries a test mode payment token. No money moves through Verigrant.
  • Passkeys Passkey approval is not on production, so a step that needs one cannot be approved.
  • The hosted door and the egress Fronts hosted by Verigrant, and the egress through Verigrant's own network, go live on their own day after the registry, the directory and Connect. Your agent can trade a pass or an agent ID for a grant at a site that runs its own door, and sends from its own network.
  • Private compute and health records Neither is switched on.
  • A price Verigrant does not charge agents.