# Verify an Identity

> Call the keyless verify-identity endpoint to check whether an IPv6 address is a Whisper agent, and read the evidence behind the verdict.

*Source: https://www.whisper.security/docs/identity/verify*

---
You have an inbound connection from an IPv6 address and you want to know whose it is. This page runs the whole proof chain in one keyless call. No account, no key, no agent on the far end.

## 1. Ask for the verdict

Pass the address, or the name it claims, as `ip`.

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

```json
{
  "is_whisper_agent": true,
  "fqdn": "ae3b051ff3bf7f478.t<tenant>.agents.whisper.online",
  "operator": "<operator label>",
  "tenant": "t<tenant>",
  "dane_ok": true,
  "jws_ok": true,
  "verified_at": "<epoch milliseconds>",
  "evidence": {
    "address": "2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478",
    "ptr": "ae3b051ff3bf7f478.t<tenant>.agents.whisper.online",
    "forward_aaaa": "2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478",
    "agent": "<agent id>",
    "allocated_at": "<epoch milliseconds>",
    "posture": "tier1.5",
    "dane_tlsa_sha256": "<hex digest>",
    "dane": {
      "usage": 3,
      "selector": 1,
      "matching": 1,
      "strong_pin": true,
      "served_leaf_matches": true
    },
    "rdap": {},
    "identity_doc": {}
  }
}
```

## 2. Read the three fields that matter

`is_whisper_agent` says the reverse and forward records agree and the allocation is current. `dane_ok` says the certificate served on the name hashes to the `TLSA` record published under it. `jws_ok` says the signed identity document on the name checks out against the key the pin names.

Inside `evidence`, `ptr` and `forward_aaaa` are the two halves of the two-way lock, and `posture` is the connectivity tier the identity is running on.

## 3. Read the other statuses

An address that is not a Whisper identity comes back as `200` with `is_whisper_agent` set to `false` and a `detail` line saying why. Malformed input comes back as `400`, also with `detail`. The endpoint does not answer `500`, so treat any other status as a transport problem and retry.

## 4. Gate on the verdict, not on the address

Verifying is not authorising. The verdict tells you which identity is calling and that the identity is real. What that identity is allowed to do is your decision, so match `fqdn` against a list you keep, at whichever granularity you need: one name, one account, or the whole identity zone.

```bash
# in your own authorisation step
test "$(jq -r .is_whisper_agent <<<"$verdict")" = true || exit 1
case "$(jq -r .fqdn <<<"$verdict")" in
  *.t<tenant>.agents.whisper.online) : ;;
  *) exit 1 ;;
esac
```

If you want to see the individual records behind the verdict, [the proof chain](/docs/identity/proofs) walks each one with the command that reads it. If you would rather not take Whisper's word for the answer at all, [re-derive it on your own machine](/docs/identity/trustless).