Skip to content
Agent Identity
Skip navigation
Agent Identity
View as Markdown

Create an Identity

Mint a routable address for one agent, capture the key it hands back once, and confirm it in public DNS.

Published

On this page (5)

Create an Identity Documentation

This page mints a new agent identity and proves it landed. The call allocates the address, writes the forward and reverse records, pins the key and publishes the registry object in one step.

Before you start

Sign in at console.whisper.security and create an API key. It looks like whisper_live_... and it goes in the X-API-Key header on every control-plane call.

1. Mint the identity

register creates a new principal with an address and a key of its own. Give it a label you will recognise, and a contact address if you want one published on the registry object.

bash
curl -s https://graph.whisper.online/api/query \
  -H "X-API-Key: <your key>" \
  -H "content-type: application/json" \
  --data-binary @- <<'JSON'
{"query": "CALL whisper.agents({op: 'register', args: {label: 'shipping-bot', contact_email: 'ops@example.com'}})"}
JSON

The reply carries the identity in result:

json
{
  "columns": ["op", "ok", "status", "result", "error", "retry_after", "elapsed_ms"],
  "rows": [
    {
      "op": "register",
      "ok": true,
      "status": 200,
      "error": null,
      "result": {
        "columns": ["agent", "address", "fqdn", "ptr", "doh_url", "resolver_ip", "member", "member_published", "api_key"],
        "rows": [
          [
            "<agent id>",
            "2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478",
            "ae3b051ff3bf7f478.t<tenant>.agents.whisper.online",
            "<reverse name under ip6.arpa>",
            "https://doh.whisper.online/<token>/dns-query",
            "<your resolver address>",
            "shipping-bot",
            true,
            "whisper_live_..."
          ]
        ]
      }
    }
  ]
}

2. Capture the two secrets now

api_key is the new agent's own key and it is shown once. Store it wherever the agent reads its credentials from, and do not expect to fetch it again.

doh_url embeds a resolver token in the path. Treat that URL as a password: anyone holding it resolves DNS as this identity.

3. Confirm it in public DNS

The reverse record names the identity, and the forward record has to point back at the same address.

bash
dig -x 2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478 +short
dig +short AAAA ae3b051ff3bf7f478.t<tenant>.agents.whisper.online

The first command prints the name, the second prints the address you started from. When they agree, the identity is live and anyone can check it without a key.

4. Read the verdict

One keyless call runs the whole chain server-side and returns a single answer:

bash
curl -s "https://rdap.whisper.online/verify-identity?ip=2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478" | jq .

is_whisper_agent is true and dane_ok is true on a healthy allocation. Verify an Identity reads the rest of the evidence, and Mint an Identity documents every argument the operation accepts, including how to allocate an extra address on the key you already hold.