Proofs And Certificates
Operate proof submission, proof lifecycle, certificate artifacts, revocation, and public verification identifiers.
Proofs And Certificates
Proofs are .der files produced by the wipe agent. The backend stores the raw
proof object before processing and uses asynchronous workers to validate,
decrypt, sign, certify, and optionally anchor the result.
Submission Routes
| Route | Auth | Use |
|---|---|---|
POST /api/v1/proofs | CLIENT_ADMIN, CLIENT_TECH, or generic proofs:write API key | Submit one multipart .der proof. |
POST /api/v1/proofs/bulk | CLIENT_ADMIN, CLIENT_TECH, or generic proofs:write API key | Submit up to 100 files or a ZIP archive, max 500 MB. |
POST /ingest/v1/proofs | Enrolled-agent API key with proofs:write | Submit one raw .der body from an enrolled agent. |
GET /ingest/v1/proofs/{id} | Enrolled-agent API key with proofs:read | Poll the status of an agent-owned proof. |
Protected writes require Idempotency-Key. The unit proof size limit is 5 MB.
The local rate limits are per authenticated principal or agent key: 100 unit
submissions per hour and 500 batch submissions per hour.
Proof Statuses
| Status | Meaning | Operator action |
|---|---|---|
RECEIVED | Stored and queued. | Watch queue depth if it persists. |
VALIDATING | Worker is validating proof envelope, agent trust, schema, and version. | Inspect worker logs if stalled. |
GENERATING_PDF | Certificate PDF is being rendered. | Check object storage and signer if failures appear. |
SIGNING | HMAC/PAdES/receipt signing is running. | Check signer readiness and key IDs. |
ANCHORING | Anchor worker is processing chain metadata. | Check chain worker and blockchain configuration. |
CERTIFIED | Certificate was produced with anchor data. | No action. |
CERTIFIED_NO_ANCHOR | Certificate was produced without active anchor data. | Accept only when product policy allows. |
AWAITING_LICENSE | Proof is valid but quota/licensing is unavailable. | Import/allocate licenses, then retry. |
FAILED | Recoverable dependency or processing failure. | Fix root cause, then retry. |
REJECTED | Terminal validation failure. | Do not replay unless validation policy was wrong. |
ABANDONED | Operator abandoned a failed proof. | Keep audit context. |
Lifecycle Actions
| Action | Route | Role |
|---|---|---|
| List proofs | GET /api/v1/proofs | CLIENT_ADMIN, CLIENT_TECH, AUDITOR |
| Read proof | GET /api/v1/proofs/{id} | CLIENT_ADMIN, CLIENT_TECH, AUDITOR, or proofs:read where accepted |
| Read status | GET /api/v1/proofs/{id}/status | CLIENT_ADMIN, CLIENT_TECH, AUDITOR, or proofs:read where accepted |
| Retry | POST /api/v1/proofs/{id}/retry | CLIENT_ADMIN |
| Full restart | POST /api/v1/proofs/{id}/full-restart | CLIENT_ADMIN |
| Abandon | POST /api/v1/proofs/{id}/abandon | CLIENT_ADMIN |
retry, full-restart, and abandon require recent MFA when
SENSITIVE_ACTION_MFA_MAX_AGE is enabled.
Certificate Routes
| Action | Route | Role |
|---|---|---|
| List certificates | GET /api/v1/certificates | CLIENT_ADMIN, CLIENT_TECH, AUDITOR |
| Read metadata | GET /api/v1/certificates/{id} | CLIENT_ADMIN, CLIENT_TECH, AUDITOR |
| Download PDF | GET /api/v1/certificates/{id}/pdf | CLIENT_ADMIN, CLIENT_TECH, AUDITOR |
| Download canonical JSON | GET /api/v1/certificates/{id}/canonical | CLIENT_ADMIN, CLIENT_TECH, AUDITOR |
| Revoke | POST /api/v1/certificates/{id}/revoke | CLIENT_ADMIN |
Certificate statuses are CERTIFIED, CERTIFIED_NO_ANCHOR, and REVOKED.
Revocation requires an audit reason and recent MFA when configured.
Public Verification
Public verification is available through:
| Route | Input |
|---|---|
GET /verify or GET /api/v1/public/verify | Query parameters. |
POST /verify or POST /api/v1/public/verify | JSON body, query parameters, or both. |
Supported identifiers are code, certificate_id, canonical_hash, and
tx_hash. When more than one identifier is supplied, they must refer to the
same certificate or the result is IDENTIFIER_MISMATCH.
Public responses never include tenant ID, organization ID, proof ID, internal storage keys, canonical JSON, HMAC value, or PDF object keys.
Operator Checks
| Symptom | First checks |
|---|---|
Proofs remain RECEIVED | proofs.validated queue, proof worker health, DB connectivity. |
Proofs become AWAITING_LICENSE | Active grants, allocation scope, user/org quota, grant validity dates. |
Proofs become FAILED | Signer, object storage, PAdES/TSA, malformed environment configuration. |
Certificates are CERTIFIED_NO_ANCHOR | BLOCKCHAIN_ENABLED, chain registry, anchor worker, Hedera readiness. |
| Public verification returns invalid/tampered | PDF/canonical/HMAC mismatch, revoked certificate, chain lookup failure, wrong identifier. |