JavaScript / TypeScript SDK

npm install @truthlock/sdk
# or
yarn add @truthlock/sdk
# or
pnpm add @truthlock/sdk

import { TruthlockClient, Algorithm, Verdict } from '@truthlock/sdk';

// 1. Create client
const client = new TruthlockClient({
  baseUrl: 'https://api.truthlocks.com',
  auth: {
    type: 'apiKey',
    apiKey: 'tl_live_...',
    tenantId: 'your-tenant-id',
  },
});

// 2. Create and trust an issuer
const issuer = await client.issuers.create({
  name: 'My Organization',
  legal_name: 'My Organization Inc.',
  display_name: 'My Org',
});
await client.issuers.trust(issuer.id);

// 3. Register a signing key
await client.keys.register(issuer.id, {
  kid: 'key-2026',
  alg: Algorithm.Ed25519,
  public_key_b64url: 'your-public-key-base64url',
});

// 4. Mint an attestation (with optional email delivery)
const attestation = await client.attestations.mint({
  issuer_id: issuer.id,
  kid: 'key-2026',
  alg: Algorithm.Ed25519,
  schema: 'degree',
  claims: {
    student_name: 'Jane Doe',
    institution: 'State University',
    degree_type: 'Bachelor of Science',
    field_of_study: 'Computer Science',
    graduation_date: '2026-05-15',
  },
  recipient_email: 'jane.doe@example.com', // optional
});

console.log('Attestation ID:', attestation.id);
console.log('Log index:', attestation.log_index);

// 5. Verify the attestation
const result = await client.verify.verifyOnline({
  attestation_id: attestation.id,
});

if (result.verdict === Verdict.Valid) {
  console.log('Attestation verified successfully');
}

const client = new TruthlockClient({
  // Required
  baseUrl: 'https://api.truthlocks.com',  // API base URL
  auth: { ... },                           // See Authentication below

  // Optional
  timeout: 30_000,              // Request timeout in ms (default: 30s)
  maxRetries: 3,                // Auto-retry with exponential backoff
  idempotencyPrefix: 'my-app',  // Prefix for auto-generated idempotency keys
});

auth: {
  type: 'apiKey',
  apiKey: 'tl_live_...',     // From Console > Settings > API Keys
  tenantId: 'your-tenant-id', // From Console > Settings > General
}

auth: {
  type: 'bearer',
  token: 'eyJhbGciOi...',  // JWT from login flow
}

auth: {
  type: 'service',
  apiKey: 'tl_svc_...',
  tenantId: 'your-tenant-id',
}

Issuers

Keys

Attestations

Verification

API Keys

Audit

Governance

import { TruthlockError, ErrorCode } from '@truthlock/sdk';

try {
  await client.attestations.mint(data);
} catch (err) {
  if (err instanceof TruthlockError) {
    console.error('Code:', err.code);      // e.g. "ISSUER_NOT_TRUSTED"
    console.error('Message:', err.message); // Human-readable message
    console.error('Status:', err.status);   // HTTP status code

    switch (err.code) {
      case ErrorCode.IssuerNotTrusted:
        // Issuer needs to be trusted before minting
        break;
      case ErrorCode.KeyNotFound:
        // Signing key not registered
        break;
      case ErrorCode.QuotaExceeded:
        // Plan limit reached
        break;
    }
  }
}

const employees = [
  { name: 'Alice', id: 'EMP-001', dept: 'Engineering' },
  { name: 'Bob',   id: 'EMP-002', dept: 'Design' },
  { name: 'Carol', id: 'EMP-003', dept: 'Product' },
];

const results = await Promise.allSettled(
  employees.map(emp =>
    client.attestations.mint({
      issuer_id: issuerId,
      kid: 'key-2026',
      alg: Algorithm.Ed25519,
      schema: 'employment-verification',
      claims: {
        employee_name: emp.name,
        employer: 'Acme Corp',
        position: 'Staff',
        department: emp.dept,
        employment_type: 'Full-time',
        start_date: '2026-01-15',
      },
      recipient_email: `${emp.name.toLowerCase()}@acme.com`,
    })
  )
);

const succeeded = results.filter(r => r.status === 'fulfilled').length;
console.log(`Minted ${succeeded}/${employees.length} attestations`);

import { verifyWebhookSignature } from '@truthlock/sdk';

app.post('/webhooks/truthlock', (req, res) => {
  const signature = req.headers['x-truthlock-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET!,
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = req.body;
  switch (event.type) {
    case 'attestation.minted':
      console.log('New attestation:', event.data.id);
      break;
    case 'attestation.revoked':
      console.log('Revoked:', event.data.id);
      break;
  }

  res.status(200).json({ received: true });
});