Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through issuing your first cryptographically signed attestation using the Truthlocks API. By the end, you’ll have a verifiable credential that anyone can validate.
Individual creator? If you want to protect a file (photo, code, design) rather than issue enterprise credentials, use the content protection guide instead. You can protect content with a single API call — no issuer setup required.
Prerequisites: You need a Truthlocks account and API key. Sign up at console.truthlocks.com if you haven’t already.
Prefer a visual approach? Every API endpoint in the API reference has an interactive playground where you can build requests, switch between Sandbox and Production environments, and send them directly from the docs.
Looking for SDKs or CLI tools? The Downloads page collects the CLI, SDKs, IDE plugins, and Docker images with copy-to-clipboard install commands.
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
Security: Your API key secret is only shown once. Store it securely in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.). Never commit API keys to version control.
Your API key will look like:
tl_live_abc123def456gh789ijklmnopqrstuv
All endpoints accept both X-API-Key: <key> and Authorization: ApiKey <key> headers. Use whichever fits your HTTP client. See authentication for details.
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": "ACTIVE",
  "trust_level": "BASIC",
  "created_at": "2026-01-13T12:00:00Z"
}
Note: New issuers are activated immediately upon creation. You can start minting attestations right away without waiting for manual approval. If your organization needs a higher trust tier, you can submit an issuer application for review.
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..."
  }'
Critical: Never share or upload private keys to Truthlocks. Only the public key is registered. Keep private keys in secure hardware (HSM) or a secrets manager.
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.
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 five verdicts:
VerdictValidMeaning
VALID✅ trueSignature valid, issuer trusted, not revoked or superseded
REVOKED❌ falseWas valid but has been revoked by issuer
SUPERSEDED❌ falseWas valid but has been superseded by a newer version
ALTERED❌ falsePayload doesn’t match signature (tampering detected)
UNKNOWN❌ falseAttestation ID not found in system

​
Next Steps

Core Concepts

Deep dive into tenants, issuers, trust levels, and the governance model.

SDK Examples

Production-ready code patterns in JavaScript, Go, Python and more.

Authentication

Learn about API keys, JWT tokens, and security best practices.

Risk Signals

Ingest fraud-detection signals and normalize identity events into your risk pipeline.

Integrations

Connect MAIP to Slack, GitHub, VS Code, AI frameworks, and more.