{"openapi":"3.1.0","info":{"title":"Sign by Kodar API","version":"1.0.0","description":"Create documents, collect qualified Smart-ID / Mobile-ID signatures (eIDAS QES), and download sealed ASiC-E containers."},"servers":[{"url":"https://api.sign.kodar.io/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Tenant API key from the developer console (kdr_…)."}},"schemas":{"Signer":{"type":"object","required":["firstName","lastName","idCode","countryCode","email"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"idCode":{"type":"string","description":"National identity number (EE/LV/LT)"},"countryCode":{"type":"string","enum":["EE","LV","LT"]},"email":{"type":"string","format":"email"},"phoneNumber":{"type":"string","description":"E.164 with country prefix; required to offer Mobile-ID"},"preferredMethods":{"type":"array","items":{"type":"string","enum":["SMART_ID","MOBILE_ID","EUDI","ADV_EIDAS"]},"description":"Optional signing-method routing preference, in order to try. Omit for the default priority. EUDI/ADV_EIDAS are dev-preview only."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/documents":{"post":{"summary":"Create a document (optionally send immediately)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","pdfBase64","signers"],"properties":{"title":{"type":"string","maxLength":200},"pdfBase64":{"type":"string","description":"Base64-encoded PDF (max 10 MB)"},"signers":{"type":"array","items":{"$ref":"#/components/schemas/Signer"},"maxItems":20},"send":{"type":"boolean","default":false},"workflow":{"type":"string","enum":["parallel","sequential"],"default":"parallel","description":"sequential invites signers one at a time in list order (Business plan and above)"},"deadline":{"type":"string","format":"date-time","description":"Signing deadline; the document expires past it (Starter plan and above)"}}}}}},"responses":{"201":{"description":"Created; includes signingLinks when send=true"},"400":{"description":"Invalid input"},"401":{"description":"Missing/invalid API key"},"413":{"description":"PDF larger than 10 MB"},"415":{"description":"Not a PDF"},"429":{"description":"Rate limited (Retry-After header)"}}},"get":{"summary":"List documents","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":50}}],"responses":{"200":{"description":"Document list, newest first"}}}},"/documents/{id}":{"get":{"summary":"Document status + signers","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Document detail"},"404":{"description":"Not found"}}}},"/documents/{id}/send":{"post":{"summary":"Send (or re-send) for signature; returns fresh signing links","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sent; previously issued links are invalidated"},"404":{"description":"Not found"},"409":{"description":"Not in a sendable state"}}}},"/algorithms":{"get":{"summary":"List signature algorithms (crypto-agility switchboard)","description":"Every signature algorithm the engine supports — classical (RSA, ECDSA) and post-quantum (ML-DSA per NIST FIPS 204) — with whether this deployment can sign with it right now. Algorithms are registry entries, not hardcoded: when qualified post-quantum certificates arrive, they appear here and your integration doesn't change.","responses":{"200":{"description":"Algorithm list","content":{"application/json":{"schema":{"type":"object","properties":{"algorithms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["rsa-sha256","ecdsa-sha256","ml-dsa-65","ml-dsa-87"]},"family":{"type":"string","enum":["RSA","EC","ML-DSA"]},"displayName":{"type":"string"},"digest":{"type":"string"},"status":{"type":"string","enum":["qualified","pqc-demo"],"description":"qualified = eIDAS-interoperable today; pqc-demo = quantum-resistant demo profile (self-signed signer, not yet interoperable — no QTSP issues post-quantum qualified certificates yet)"},"enabled":{"type":"boolean"}}}}}}}}}}}},"/seal":{"post":{"summary":"Apply the organisation e-seal (Enterprise, metered)","description":"Seals a PDF into a fresh ASiC-E container, or adds a seal signature to an existing container. Pass algorithm: \"ml-dsa-65\" for a post-quantum (NIST FIPS 204) demo seal — quantum-resistant content signature with a classical qualified timestamp; the container is a demo profile until qualified PQC certificates and standardized XAdES algorithm identifiers exist. Validate PQC containers via POST /validate, which routes them to the in-house engine.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentBase64":{"type":"string","description":"Base64 PDF — seals into a fresh container"},"containerBase64":{"type":"string","description":"Base64 .asice — adds a seal signature"},"filename":{"type":"string"},"algorithm":{"type":"string","enum":["ml-dsa-65","ml-dsa-87"],"description":"Omit for the classical qualified e-seal; set for the post-quantum demo seal"}}}}}},"responses":{"200":{"description":"Sealed; response includes asiceBase64 and per-signature report"},"400":{"description":"Invalid input / algorithm mismatch"},"403":{"description":"Enterprise plan required"},"404":{"description":"Post-quantum sealing not enabled on this deployment"},"503":{"description":"No seal certificate provisioned"}}}},"/validate":{"post":{"summary":"Validate a signed container (metered)","description":"Re-verifies every signature in an ASiC-E/BDOC container against the EU trusted lists. Counted against the monthly validation allowance. Enterprise plans receive the full qualified report (profile, trusted timestamps, findings). Post-quantum (ML-DSA) containers route to the in-house engine automatically; the report carries validationEngine and interoperability fields.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["containerBase64"],"properties":{"containerBase64":{"type":"string","description":"Base64-encoded .asice/.bdoc bytes (max 30 MB)"}}}}}},"responses":{"200":{"description":"Validation verdict + per-signature report"},"403":{"description":"Validation allowance used up"},"413":{"description":"Container larger than 30 MB"},"422":{"description":"Bytes are not a readable container"}}}},"/documents/{id}/container":{"get":{"summary":"Download the sealed ASiC-E container","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The .asice bytes","content":{"application/vnd.etsi.asic-e+zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found"},"409":{"description":"Container not ready — not all signers have signed"}}}}}}