BurnLedger API (1.0.0)

Runs every admission gate a registration would run — DSN parsing, transport-security floor, connectivity, read-only enforcement — and persists nothing. Answers 200 even when a gate failed: the request succeeded in telling the caller what is wrong, and a non-2xx would make "your password is wrong" indistinguishable from "the test could not run". Check ok and walk steps.

Removes the system from the team: it stops being listed, health checks stop, its name and MaxSystems slot are freed, and it can no longer be attested against. A system that is referenced by attestations is retired rather than erased, so the records that name it stay verifiable; the caller sees no difference, and either way the system answers 404 afterwards.

Returns the stored result of the last health check without probing the system. The body is the health fields alone, not the full System.

Queries all specified systems for the subject identifier and signs an attestation payload. Returns immediately with status PENDING_VERIFICATION. Call POST /v1/attestations/{id}/verify after data deletion to produce a verification record.

Creates attestations for up to 100 subject identifiers concurrently. Individual failures are collected in the errors field and do not abort the batch: the response is 200 whether every subject succeeded or none did, so inspect errors rather than the status code. A 400 is returned only when the request itself is malformed (for example a system listed twice in system_ids).

Re-queries all systems for the original subject identifier. If all systems return zero records the attestation transitions to CERTIFIED and a verification record is issued and appended to the transparency log. If any records remain the status is set to VERIFICATION_FAILED.

Unauthenticated, deliberately. Returns a signed status statement for the verification record — ACTIVE or REVOKED — valid for the window it states. The audience is a relying party holding the verification record: a regulator, an auditor, the customer's customer. Verify the signature against the published keys, and treat a missing or expired statement as revocation-unknown, never as valid.

Revokes up to 100 verification records in one call, under a single reason. Individual failures are collected in the errors field and do not abort the batch: the response is 200 whether every record was revoked or none was, so inspect errors rather than the status code. A 400 is returned only when the request itself is malformed (no reason, an empty list, more than 100 ids, or the same id twice) and in that case nothing is revoked.

Each record takes the same path as POST /v1/certificates/{id}/revoke — the same revocation entry in the transparency log, the same certificate.revoked webhook, the same audit row — so a batched revocation is indistinguishable from an individual one afterwards. Revoking an already-revoked record succeeds and changes nothing.

The returned records omit status_statement. Revoking invalidates the cached statement, so stapling one per record would mean a fresh signing round trip for every item in the batch; fetch GET /v1/certificates/{id}/status for the records you need a signed statement for.

Returns aggregate counts and monthly issuance breakdown for the customer.

Streams ONE PAGE of verification records as CSV or JSONL, oldest first, up to 10,000 records. Optionally filter by status and date range.

Every response ends in a footer record, and a response without one is truncated. The footer carries the number of verification record records in that response and the cursor for the next page. Pass that cursor back as cursor and repeat until the footer's next cursor is empty; the concatenation of the pages is the complete export.

• CSV: a final row whose first column is _export_footer, second column the record count, third column the next cursor (empty when the export is complete). It has the same column count as a record row, so a strict reader still parses the file.
• JSONL: a final object {"_export_footer": true, "record_count": N, "next_cursor": "…" | null}.

The footer is in the body rather than a header on purpose: the file is the evidence, and it gets saved and handed on where headers do not follow. If the export fails part-way — the query dies after the 200 and the first records are already on the wire — the response ends with NO footer. That is the only signal left at that point, so a client must treat a footerless body as incomplete and retry rather than keep it.

The URL must be HTTPS and must not resolve to a private or loopback address (SSRF protection). The returned secret is shown only once; use it to verify the X-BurnLedger-Signature header on incoming events (see the Webhook.secret schema for the exact preimage and a worked example).

Stages a new signing secret. Until rotation_expires_at (24 hours) every delivery carries two comma-separated digests in X-BurnLedger-Signature, the current secret's then the new one's, so the receiver can switch at any point in the window. Call commit-rotation once it has; if the window lapses first the staged secret is abandoned and deliveries carry the current secret's signature alone. Only one rotation can be staged at a time: while one is inside its window a second call is refused with 409 rather than replacing the secret already handed out.

Retires the old secret; only the new secret signs from this point. Must be called within the rotation window.

Returns unresolved failed deliveries (dead letter queue): events whose first delivery failed and that are either waiting for their next automatic retry (next_attempt_at set) or parked after exhausting the automatic attempts (next_attempt_at null). Use POST .../retry to queue another attempt or DELETE to acknowledge and discard.

Queues the delivery for the next retry sweep (within about five minutes) regardless of how many automatic attempts it has used. The request returns as soon as the delivery is queued; the attempt itself runs in the background. Poll GET /v1/webhooks/deliveries/failed: the delivery disappears once it succeeds, or stays listed with an incremented attempts and updated error_message if it fails again.

Marks the failed delivery as resolved without retrying. Use this to discard deliveries that are no longer relevant.

When email verification is enabled, sends a verification code and returns a customer_id. When disabled, creates the customer and returns credentials directly.

Verifies a Google ID token. A returning user whose account has no second factor receives session_token. One whose account has TOTP enrolled receives totp_required: true and a totp_challenge instead, and no session until the challenge is presented with a code to POST /v1/auth/login/totp. The challenge is good for five minutes.

Second step of a login that answered with totp_required. Takes the totp_challenge from that response together with the six-digit code from the authenticator app, or an eight-character recovery code, and returns the session token the first step withheld. Five consecutive wrong codes lock the account's second factor for fifteen minutes.