Quick Start

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.

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.

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.

Every issuer needs at least one signing key (Ed25519 recommended; ES256, ES384, RS256, PS256 also supported). 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' }));
});

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.

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.

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:

Verdict	Valid	Meaning
`VALID`	✅ true	Signature valid, issuer trusted, not revoked or superseded
`REVOKED`	❌ false	Was valid but has been revoked by issuer
`SUPERSEDED`	❌ false	Was valid but has been superseded by a newer version
`ALTERED`	❌ false	Payload doesn’t match signature (tampering detected)
`UNKNOWN`	❌ false	Attestation 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.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

Understanding Verdicts

Next Steps

Core Concepts

SDK Examples

Authentication

Risk Signals

Integrations

​Understanding Verdicts

​Next Steps

Core Concepts

SDK Examples

Authentication

Risk Signals

Integrations

Understanding Verdicts

Next Steps