Public verification API

Proof that systems can interrogate.

Public API routes expose credential status, JSON-LD proof, PDFs, verification receipts, issuer profiles, and Passport lookups. They are read-only, rate limited, and explicit when the registry cannot complete a check.

Read the trust model Open the verifier

Access: No API key
Contract: Read-only routes
Failure: Explicit 503 state

Registry contract

Illustrative contract view

Public

requestGET /api/public/credentials/verify/NV-EXAMPLE-0001

response200 // verification.overall_status

issuerapproved profile + verified domain

integritysignature + payload hash + lifecycle

boundary503 is never treated as verified

Use your configured Nyvarra host in non-production environments. Public responses intentionally exclude private holder emails, internal user IDs, and private Passport settings.

Endpoint ledger

One public contract across the proof lifecycle.

The production base URL is https://nyvarra.app. Every route below is intentionally scoped to a public verification, export, receipt, issuer, or Passport workflow.

GET

Credential verification

Returns the public credential view, verification checks, status, replacement credential if superseded, and trust evidence.

/api/public/credentials/verify/[code]

240 requests/minute

GET

Credential PDF

Streams the archived or regenerated credential PDF for the public serial.

/api/public/credentials/[code]/pdf

120 requests/minute

GET

JSON-LD credential

Returns the signed credential payload as application/ld+json.

/api/public/credentials/[code]/credential

240 requests/minute

GET

Open Badge 3.0 export

Exports the exact signed JSON-LD document, or compact VC-JWT when Accept: application/jwt is sent.

/api/public/credentials/[code]/open-badge

240 requests/minute

POST

Open Badge validation

Checks required contexts and fields, date validity, and supported Ed25519 proof integrity.

/api/open-badges/validate

60 requests/minute

GET

Verification receipt PDF

Generates a live PDF receipt containing status, checks, hashes, issuer context, and checked-at timestamp.

/api/public/credentials/[code]/verification-receipt

120 requests/minute

GET

Issuer profile

Returns a sanitized public issuer profile, catalog, counts, and domain trust signals.

/api/public/issuers/[slug]

180 requests/minute

GET

Passport lookup

Returns a privacy-filtered public Passport view. Add ?verification=1 for verifier-focused views.

/api/public/passports/[handle]

180 requests/minute

Status semantics

The decision is data, not decoration.

The public page and API use the same core verification service. Client systems should branch on verification.overall_status and should not infer trust from visual certificate layout.

01verified

Cryptographic proof passes and the credential lifecycle is active.

02revoked

The issuer withdrew the credential. The original record remains visible.

03superseded

A corrected credential replaced this serial.

04expired

The credential passed its expiration date.

05tampered

Signature, proof payload, or stored hash validation failed.

06not_found

No credential exists for the requested serial or code.

Unavailable is not verified.

A 503 means the registry check did not complete. Do not cache it as a verified result, and do not substitute a visual certificate check.

SOURCE OF TRUTH // verification.overall_status

Response contract

A clear answer with the evidence still attached.

The response includes a sanitized certificate view, verification checks, and a replacement credential when a serial has been superseded. Use the receipt URL when a recruiter or compliance team needs a portable verification artifact.

200

Verification completed.

404

Credential, issuer, or Passport was not found.

429

Rate limit exceeded. Respect retry-after.

503

Registry temporarily unavailable. Do not treat as verified.

application/json

{
  "success": true,
  "certificate": {
    "serial": "NV-EXAMPLE-0001",
    "status": "issued",
    "verification_url": "https://nyvarra.app/verify/NV-EXAMPLE-0001",
    "verification_receipt_url": "https://nyvarra.app/api/public/credentials/NV-EXAMPLE-0001/verification-receipt",
    "issuer": {
      "name": "Example University",
      "slug": "example-university",
      "verified_domain": "example.edu"
    }
  },
  "verification": {
    "overall_status": "verified",
    "cryptographic_valid": true,
    "signature_valid": true,
    "payload_matches_proof": true,
    "payload_hash_matches": true,
    "verified_at": "2026-07-10T12:00:00.000Z"
  },
  "replacement_certificate": null
}

Illustrative credential verification response. Replacement credential data is returned when a serial has been superseded.

Operating boundaries

Public access, bounded by explicit controls.

The public surface is intentionally easy to call and intentionally narrow in what it returns.

Rate limit

Request pressure is visible

Public routes return x-ratelimit headers and retry-after when throttled.

Authentication

No API key is required

Current public verification routes are read-only and do not require API keys.

Failure state

Incomplete checks fail closed

A 503 means the registry check did not complete. Do not cache it as a verified result.