Skip to main content
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 TypeDescription
attestation.mintedTriggered when the platform has signed the record.
issuer.suspendedTriggered if the issuer’s trust rating changes.
billing.limit_reachedHigh-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:
  1. Original Data: The payload you minted.
  2. Issuer Signature: Your cryptographic proof of intent.
  3. 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.
Use our SDKs to handle retries, signature verification, and payload serialization automatically.