Issuer API
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.
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, plus the recipient's registration number and file links, since it's your own record. File downloads require an authorized browser session; the lookup API key alone does not authorize a download. 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
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"]}'{
"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" }]
}
]
}