Pass

A hannu Pass authenticates a visit. When an Operator arrives to do a task, they present a Pass — a delegated, one-time credential that proves this visit is the real, authorised one. The verify endpoint is how a checker confirms the Pass is genuine and sees just enough to confirm the person: the Operator's first name, last initial, photo, and reputation tier, plus the client who sent them. It never exposes contact details or government IDs.

This is a public Tier-A endpoint: a person or system at the point of the visit can verify a Pass without holding any Hannu credential, so no API key is sent. The scanned token goes in the POST body — the field is token — so it never lands in a request log.

curl -X POST https://api.hannu.africa/v1/pass/verify \
  -H "Authorization: Bearer $HANNU_KEY"

An authorized response confirms the visit is real and current, and shows the verifier the Operator's first name, last initial, photo, and tier, plus the client who sent them:

{
  "data": {
    "status": "authorized",
    "credential_ref": "cred_7a20",
    "operator": {
      "first_name": "Amara",
      "last_initial": "O",
      "tier": "verified",
      "photo_url": "https://…"
    },
    "sent_by": "Acme Logistics",
    "scope": {
      "action_class": "field_verification",
      "task_title": "Confirm storefront at 23 Commercial Avenue, Yaba",
      "zone_ref": "lagos_yaba"
    },
    "issued_at": "2026-07-17T13:30:00Z",
    "expires_at": "2026-07-17T14:30:00Z",
    "scan_count": 1
  }
}

If the Pass is expired, revoked, already spent, or unknown, the endpoint returns a not-authorized answer with no Operator or client details:

{
  "data": {
    "status": "not_authorized",
    "reason": "expired"
  }
}

The verify page shows just enough to confirm the person on the doorstep — the Operator's first name, last initial, photo, and tier, plus the client who sent them (sent_by). It never exposes the Operator's phone, address, full name, or BVN/NIN.