Agent tokens (`agent-zk`)#

An enrolled agent authenticates with an agent-zk deed — a zero-knowledge membership proof; ZkAgent.mintDeed (every language) is the entire mint API, with no browser, issuer, or client secret involved. See Concepts for the mental model.

Don't need on-chain enrolment? Use `user-sig` instead#

If your agent authenticates straight to an app's own API and doesn't need per-agent revocation or anonymous membership, permissionless user-sig needs no enrolment round trip — any signing key works. See Wallet login; authenticate() composes discover → challenge → mint for you:

import { authenticate } from "@grantor/agent";
import { Registry } from "@grantor/agent/registry";

const deed = await authenticate("https://api.example.com", signMessage, {
  chainReader,
  registry: Registry.canonical(),   // the SDK pins the canonical registry for you
  rpcUrl,
});

chainReader (an eth_call seam) and registry (a RegistryRef — the SDK pins the canonical registry for you; a custom address exists only on the licensed dedicated path) are REQUIRED: authenticate() uses them to verify the application can show a tenant admin's on-chain vouch for this origin before it signs anything. See Constructing a chainReader.

The `agent-zk` recipe#

authenticate() does not apply to agent-zk — an already-enrolled agent composes discover(), a challenge fetch, and ZkAgent.mintDeed by hand instead. The full worked example (all four languages), the same-origin rule, and the origin-provenance vouch check mintDeed performs before it proves, are documented once, in Sovereign tier § What it is and § Discovery — how an agent finds all this. Read those rather than a second copy here.

⚠️ Read the caveats, not just the recipe. mintDeed's provenance check closes agent-zk cross-origin linkability and membership disclosure by prevention — but only when your holder actually runs it, and only against an origin that has published a valid vouch. See Sovereign tier § Origin binding — what this closes, and what still does not and § Origin provenance for exactly what is and is not closed today.

Prerequisites (one-time, on-chain, done by the tenant operator)#

Before an agent can mint an agent-zk deed, the tenant operator must, on GrantorRegistry:

createTenant and keep it funded (Active or Grace — see Concepts).
registerZkAgent — enrol the agent's Semaphore identity commitment in the tenant's on-chain membership tree (registerZkAgentBatch to enrol several agents in one call).
Sign and publish an origin vouch for the app's origin, so ZkAgent.mintDeed's provenance check can pass — see Sovereign tier § Origin provenance. A tenant admin revokes a vouch with bumpOriginEpoch if an origin is decommissioned or compromised.

Verifying it#

Your app verifies an agent-zk deed exactly the way it verifies a user-sig one — the same DeedGuard/DeedVerifier, the same verify_deed call. See Verify a deed.

Full agent-integration walkthrough#

See Agent integration and Agent onboarding.

Agent tokens (agent-zk)#