Technical Integration Pack

Developer's Quickstart & API Strategy

1. Authentication

All API requests must be authenticated via Bearer tokens.

API Keys: Issued via the Tenant Console (Security > API Keys).
Scopes: Keys are scoped to specific actions (e.g., mint, verify, read_audit).
Rotation: We recommend a 90-day rotation policy. Invalidate keys immediately via the DELETE endpoint upon compromise.

2. The Minting Flow

To issue an attestation, POST a JSON payload to /v1/attestations/mint.

{
  "template_key": "academic_transcript",
  "payload": {
    "student_id": "STU123",
    "gpa": "3.8"
  },
  "recipient_email": "student@university.edu"
}

3. Webhooks & Eventing

Truthlocks uses webhooks to notify your system of state changes.

Event Type	Description
`attestation.minted`	Triggered when the platform has signed the record.
`issuer.suspended`	Triggered if the issuer's trust rating changes.
`billing.limit_reached`	High-priority notification for quota management.

Verification: Always verify the X-Truthlock-Signature header using your endpoint's shared secret.

4. Proof Bundles

A Proof Bundle is a signed JSON object containing:

Original Data: The payload you minted.
Issuer Signature: Your cryptographic proof of intent.
Platform Checkpoint: Truthlocks' proof of the network state at the time of minting.

5. Rate Limits & Quotas

Limits are applied per-tenant based on your subscription tier:

Global Burst: 500 requests per 10 seconds.
Monthly Minting Quota: Defined in your Enterprise Agreement (viewable in /v1/billing/usage).

6. Environment Separation

We provide two distinct environments:

Sandbox (sandbox.truthlocks.com): For testing with mock keys and ephemeral data.
Production (api.truthlocks.com): Federated for high-stakes issuing.

[!TIP] Use our SDKs to handle retries, signature verification, and payload serialization automatically.