ZADA

API Reference

All requests are JSON over HTTPS. Authenticate with X-API-KEY: zada_….

POST/api/v1/issueX-API-KEY (scope: issue)

Sign a payload through the full ZADA pipeline and (optionally) render an A4 PDF.

Request
{
  "issuer_id": "<uuid>",
  "subject": "patient-1234",
  "claims": { "type": "HealthCertificate", "result": "negative" },
  "generate_pdf": true
}
Response
{
  "zada": "ZADA:6BFOXN%TS3DH...",
  "pdf_url": "https://.../credentials/<tenant>/<id>.pdf",
  "issuer": { "name": "...", "kid": "...", "x5t_s256": "..." },
  "issued_at": "2026-04-20T12:00:00Z"
}
POST/api/v1/verifyX-API-KEY (scope: verify)

Decode and verify a ZADA string against the cached trust registry.

Request
{ "zada": "ZADA:6BFOXN%..." }
Response
{
  "valid": true,
  "issuer": { "name": "...", "kid": "...", "x5t_s256": "...", "trust_source": "registry_cache" },
  "algorithm": "EdDSA",
  "claims": { ... }
}
GET/api/v1/registry/syncPublic

Returns a CBOR-encoded, COSE_Sign1-signed bundle of trusted issuers for offline verification.

Request
—
Response
Binary application/cose payload (download as zada-trust-bundle.cose)
POST/api/v1/registry/refreshX-API-KEY (scope: issue)

Pull latest entries from the configured ZADA mirror (env MOCK_ZADA_URL) into trust_registry_cache. Seeds 2 mock issuers if no URL is set.

Request
—
Response
{ "refreshed": 2, "source": "mock-seed" }

Pipeline format

Claims
  └─ CBOR encode
      └─ COSE_Sign1 (alg: EdDSA, kid, x5t#S256)
          └─ ZLIB deflate
              └─ Base45 encode
                  └─ Prepend "ZADA:"
                      └─ QR code (Level H)

curl example

curl -X POST https://YOUR_HOST/api/v1/issue \
  -H "X-API-KEY: zada_..." \
  -H "Content-Type: application/json" \
  -d '{"issuer_id":"<uuid>","subject":"abc","claims":{"type":"Demo"}}'