Quick Start Guide

Step 1: Get Your API Key

Navigate to the API Keys section in your console dashboard. Create a new API key with the following scopes:

• issuers:read - View your issuers
• issuers:write - Create and manage issuers
• attestations:mint - Create new attestations

Your API key will look like:

tl_live_abc123def456gh789ijklmnopqrstuv

Step 2: Create an Issuer

Issuers are entities that can sign attestations. Each issuer has a unique identity, cryptographic keys, and a trust status. Create your first issuer:

Request

curl -X POST https://api.truthlocks.com/v1/issuers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tl_live_your_api_key" \
  -d '{
    "name": "Acme University",
    "domain": "acme.edu"
  }'

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme University",
  "domain": "acme.edu",
  "status": "PENDING",
  "trust_level": "BASIC",
  "created_at": "2026-01-13T12:00:00Z"
}

Step 3: Register a Signing Key

Every issuer needs at least one Ed25519 signing key. You can generate keys locally or use our SDK to create them.

Generate a Key Pair (Node.js)

import { generateKeyPair } from 'crypto';

generateKeyPair('ed25519', (err, publicKey, privateKey) => {
  console.log('Public Key (PEM):', publicKey.export({ type: 'spki', format: 'pem' }));
  console.log('Private Key (PEM):', privateKey.export({ type: 'pkcs8', format: 'pem' }));
});

Register the Public Key

curl -X POST https://api.truthlocks.com/v1/issuers/550e8400-e29b-41d4-a716-446655440000/keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tl_live_your_api_key" \
  -d '{
    "kid": "ed-key-2026",
    "algorithm": "Ed25519",
    "public_key": "MCowBQYDK2VwAyEAGb9Y2LvOsSglb2wUInSMKDpXm1QL..."
  }'

Step 4: Mint an Attestation

Now you can create your first attestation. This example issues a verified email claim for a user:

Request

curl -X POST https://api.truthlocks.com/v1/attestations/mint \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tl_live_your_api_key" \
  -d '{
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "kid": "ed-key-2026",
    "subject": "user:john.doe@example.com",
    "claim": "email_verified",
    "value": "john.doe@example.com",
    "metadata": {
      "verified_at": "2026-01-13T12:00:00Z",
      "verification_method": "otp"
    }
  }'

Response (201 Created)

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
  "kid": "ed-key-2026",
  "status": "VALID",
  "payload": {
    "subject": "user:john.doe@example.com",
    "claim": "email_verified",
    "value": "john.doe@example.com"
  },
  "signature": "MEUCIQDf7KxF5bXmz...",
  "log_index": 42,
  "created_at": "2026-01-13T12:05:00Z"
}

Congratulations! You've just issued a cryptographically signed attestation. The log_index is its position in the transparency log, providing proof of when it was created.

Step 5: Verify the Attestation

Anyone can verify your attestation using its ID. The verification endpoint is public and requires no authentication:

Request

curl -X POST https://api.truthlocks.com/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "attestation_id": "660e8400-e29b-41d4-a716-446655440001"
  }'

Response (200 OK - Valid)

{
  "verdict": "VALID",
  "valid": true,
  "details": {
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "issuer_name": "Acme University",
    "issuer_domain": "acme.edu",
    "issuer_trust_level": "VERIFIED",
    "log_index": 42,
    "created_at": "2026-01-13T12:05:00Z",
    "checked_at": "2026-01-13T12:10:00Z"
  }
}

Understanding Verdicts

The verification endpoint returns one of four verdicts:

Next Steps