Truthlocks Python SDK

Synchronous Python client for Truthlocks. Requires Python 3.9 or later.

python -m pip install truthlock

Verify a record

Set TRUTHLOCKS_API_KEY and TRUTHLOCKS_ATTESTATION_ID before running:

import os
from truthlock import TruthlockClient, Verdict

with TruthlockClient(api_key=os.environ["TRUTHLOCKS_API_KEY"]) as client:
    result = client.verify.verify_online(os.environ["TRUTHLOCKS_ATTESTATION_ID"])
    print(result.verdict.value)
    if result.verdict == Verdict.VALID:
        print("Record verified")

A tl_test_ key selects the sandbox host by default. Use base_url to override it; production and sandbox credentials must match the selected host. The workspace is derived from credentials, not a tenant header. A record-only verdict does not check an unrelated local file: pass payload_b64url or document_hash_hex for content checks.

Mint bytes

Use an existing issuer and signing key that is available for signing in your workspace:

import base64
import os
import uuid
from truthlock import TruthlockClient

payload = base64.urlsafe_b64encode(b"Example record").rstrip(b"=").decode("ascii")
request_key = str(uuid.uuid4())  # retain alongside the body for a retry
with TruthlockClient(api_key=os.environ["TRUTHLOCKS_API_KEY"]) as client:
    record = client.attestations.mint(
        issuer_id=os.environ["TRUTHLOCKS_ISSUER_ID"],
        kid=os.environ["TRUTHLOCKS_KEY_ID"],
        alg=os.environ["TRUTHLOCKS_ALGORITHM"],
        payload_b64url=payload,
        idempotency_key=request_key,
    )
    print(record.attestation_id)

The algorithm must match the signing key. Registering a public key does not upload its private key or enable service-side signing with that private key.

Behavior

• Resources: issuers, keys, attestations, online verification and receipts.
• Current proof bundles retain their key, checkpoint, inclusion proof and audit fields. Downloading a bundle does not verify it offline.
• Verdict parsing accepts uppercase API verdicts while keeping the existing lowercase enum values.
• Writes are not automatically replayed unless their server route supports idempotency. Retain the same key and body when retrying one mint.
• HTTP errors and malformed successful JSON responses raise SDK errors.
• The main client is synchronous. Its separate registration helper is asynchronous; it does not make other resource methods awaitable.

Use a context manager or call close() when finished. Keep credentials out of source control and use the API reference for environment and authorization requirements.

Documentation · Issues