Reference

Issuer API

For organizations that issue on Nyvarra. Your own server reads your own certificates by serial, as they stand today, for example to list a member's certificates on your website or to keep your records in step.

Reading through the issuer API isn't a verification: it isn't added to a certificate's check count. To check someone else's certificate, use the Verification API.

Authentication

Send your key as a bearer token in the Authorization header. Keys start with nyv_.

A key reads only the certificates of the one organization it belongs to. It can't issue, change or withdraw anything.
Nyvarra keeps only a SHA-256 of the key, so a lost key can't be shown again. It is replaced instead.
Keep it on your server, in an environment variable or secret store. Never put it in a web page or an app.
A revoked key stops working at once and gets 401.

Header

Authorization: Bearer nyv_k3x9q2ma_••••••••••••••••••••••••••••••••••••••••••

Look up certificates

POST/api/issuer/v1/certificates/lookup

Returns your certificates for up to 100 serials in one call, in the order you sent them. When a certificate was corrected, you get the current correction, with the serials it replaced, so you always show the version that verifies today.

Body

serialsstring[]required: Between 1 and 100 serials. Duplicates are ignored, and case doesn't matter.

Returns, for each serial

serialstring: The serial you sent.
foundboolean: False when no certificate of yours has that serial. Another organization's serial also reads as not found.
certificateobject | null: The certificate as it stands now, in the same shape as the verify endpoint's certificate. A withdrawn one comes back with its status and no file links.
replacedobject[]: The serials it went through, oldest first, when it was corrected. Empty otherwise.

Responses

200: The lookup ran. Check found for each serial.
400: No serials, or more than 100.
401: The key is missing, malformed or revoked.
429: Rate limited for this key.
500: Something went wrong on Nyvarra's side. Retry later.

Rate limit: 600 requests a minute, per key

Request

curl https://nyvarra.app/api/issuer/v1/certificates/lookup \
  -H "Authorization: Bearer $NYVARRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serials": ["NV-000142", "NV-000143"]}'

200 OK

{
  "success": true,
  "certificates": [
    {
      "serial": "NV-000142",
      "found": true,
      "certificate": {
        "serial": "NV-000142",
        "status": "issued",
        "verification_url": "https://nyvarra.app/verify/NV-7KQ2M9XHCP4WRTZB-1187",
        "pdf_url": "https://nyvarra.app/api/public/credentials/NV-7KQ2M9XHCP4WRTZB-1187/pdf",
        "recipient": { "full_name": "Ayesha Siddiqui", "registration_number": null },
        "event": { "title": "Basic Life Support Workshop", "…": "…" },
        "…": "…"
      },
      "replaced": []
    },
    {
      "serial": "NV-000143",
      "found": true,
      "certificate": { "serial": "NV-000188", "status": "issued", "…": "…" },
      "replaced": [{ "serial": "NV-000143", "status": "superseded" }]
    }
  ]
}