BurnLedger Python SDK

Python client for the BurnLedger API — cryptographic deletion certificates for regulatory compliance.

Scope

The SDK covers the data plane: systems, attestations, certificates, webhooks, API keys, /v1/me, and the transparency log — everything involved in measuring a datastore and verifying what came back.

Account management (teams, TOTP enrolment, subscriptions, invoices, the audit log, billing) is deliberately not part of the SDK. Those are administrative actions people take once, in the dashboard at https://dashboard.burnledger.io, and they are available on the raw /v1 API for anyone who needs to automate them.

Install

pip install burnledger

Requirements: Python 3.10+

Quick Start

from burnledger import BurnLedger

with BurnLedger(api_key="dp_...") as dp:
    # 1. Attest — snapshot systems before deletion
    att = dp.attest("user@example.com", system_ids=["sys_abc", "sys_def"])

    # 2. Delete data (your code, your tools)

    # 3. Verify — confirm deletion and get certificate
    result = dp.verify(att.id, "user@example.com", timeout=60)

    # 4. Download certificate PDF
    dp.save_pdf(result.certificate.id, "./deletion-cert.pdf")

Async

from burnledger import AsyncBurnLedger

async with AsyncBurnLedger(api_key="dp_...") as dp:
    att = await dp.attest("user@example.com", system_ids=["sys_abc"])
    result = await dp.verify(att.id, "user@example.com", timeout=60)

Offline Verification

Verify certificates without network access using Ed25519 signatures:

from burnledger import verify_certificate, verify_transparency, PublicKeyInfo

key = PublicKeyInfo.from_hex("abcdef...", revoked=False)
keys = {key.key_id: key}

cert_result = verify_certificate(certificate, keys)
# VerificationResult.VALID or raises VerificationError

log_result = verify_transparency(certificate, keys)
# TransparencyResult.INCLUDED or raises VerificationError

Webhook Verification

Verify incoming webhook signatures (HMAC-SHA256):

from burnledger import verify_webhook_signature

valid = verify_webhook_signature(
    secret=webhook_secret,         # from dp.register_webhook()
    body=request.body,             # raw request body
    signature=request.headers["X-BurnLedger-Signature"],
)

API Reference

Client

BurnLedger(
    api_key: str,
    *,
    base_url: str = "https://api.burnledger.io",
    timeout: float = 30.0,
    max_retries: int = 2,
)

Systems

Attestations

Certificates

batch_revoke_certificates takes up to MAX_BATCH_REVOKE (100) ids under one reason and returns whether all, some or none were revoked: the failures are in errors, each naming the request index and certificate_id, so a partially failed batch is inspected, not caught. More than 100 ids raises ValueError before any request is made; chunk larger sets by MAX_BATCH_REVOKE.

Webhooks

API Keys

Transparency Log

These methods do not require authentication.

Pagination

All list_* methods return a paginator that auto-fetches pages:

for cert in dp.list_certificates():
    print(cert.id)

# async
async for cert in dp.list_certificates():
    print(cert.id)

License

MIT