Skip to main content
This guide explains the fundamental building blocks of the Truthlocks platform. Understanding these concepts is essential for effective integration.

​
Tenants

A tenant is the top-level organizational unit in Truthlocks. Each tenant represents a distinct customer or organization with complete data isolation.
PropertyDescription
idUnique UUID identifying the tenant
nameHuman-readable organization name
slugURL-safe identifier (e.g., acme-corp)
tierSubscription tier: FREE, STARTER, PROFESSIONAL, ENTERPRISE
statusACTIVE, SUSPENDED, or DELETED

​
Multi-Tenancy Guarantees

  • Data Isolation: Each tenant’s data is completely isolated at the database level
  • Resource Limits: Rate limits and quotas are enforced per-tenant
  • API Key Scoping: API keys are bound to a single tenant and cannot access other tenants’ data
  • Audit Separation: Audit logs are partitioned by tenant

​
Issuers

An issuer is an entity that can create and sign attestations. Issuers represent organizations, institutions, or services that make claims about subjects.

Identity

Each issuer has a verified domain (e.g., acme.edu) that establishes their real-world identity.

Cryptographic Keys

Issuers register Ed25519 public keys used to verify attestation signatures.

Trust Status

New issuers are activated immediately on creation. Higher trust tiers require an application review: ACTIVE → SUSPENDED.

Trust Level

BASIC, VERIFIED, or PREMIUM based on identity verification depth.

​
Issuer lifecycle

                    ┌──────────────┐
                    │   CREATED    │
                    └───────┬──────┘
                            │ auto-activated
                            ▼
                    ┌──────────────┐
                    │    ACTIVE    │  ← Ready to mint (BASIC trust)
                    └───────┬──────┘
                            │
            suspend │               │ apply for higher tier
                    ▼               ▼
            ┌──────────────┐  ┌──────────────┐
            │   SUSPENDED  │  │   IN REVIEW  │
            └──────────────┘  └───────┬──────┘
                                      │
                              approve │ reject
                              ▼               ▼
                      ┌──────────────┐  ┌──────────────┐
                      │    ACTIVE    │  │   REJECTED   │
                      │ (higher tier)│  │ (keeps BASIC)│
                      └──────────────┘  └──────────────┘
New issuers are activated immediately with the Basic trust level. No manual approval is required to start minting attestations. To upgrade to a higher trust tier (Verified Organization, Government Entity, or Accredited Institution), submit an issuer application for review.

​
Attestations

An attestation is a cryptographically signed claim made by an issuer about a subject. Attestations are the core primitive of the Truthlocks system.

​
Attestation Structure

{
  "id": "uuid", // Unique identifier
  "issuer_id": "uuid", // Who signed it
  "kid": "string", // Key used to sign
  "status": "VALID", // Current status
  "payload": {
    "subject": "string", // Who/what the claim is about
    "claim": "string", // Type of claim (e.g., "verified_email")
    "value": "any", // The actual claim data
    "metadata": {} // Optional additional data
  },
  "signature": "base64", // Ed25519 signature
  "log_index": 42, // Position in transparency log
  "created_at": "datetime"
}

​
Attestation Properties

PropertyDescription
ImmutableOnce created, the payload and signature cannot be modified
RevocableIssuers can revoke attestations, updating status to REVOKED
SupersedableIssuers can supersede an attestation with a new version, creating an auditable chain while preserving the original
PortableAttestation ID can be shared and verified anywhere
AuditableEvery operation is logged in the transparency log

​
Consumer protections

A consumer protection is an attestation created through the simplified consumer mint flow, designed for individual creators. You hash your file client-side (SHA-256) and submit the hash along with metadata like title, category, and content type. Truthlocks provisions your signing identity automatically on first use. The consumer mint response includes:
FieldDescription
protection_idUnique ID for the protection record
attestation_idThe underlying attestation ID (used for verification)
content_hashThe SHA-256 hash you submitted, echoed back for confirmation
protected_atExact timestamp when the content was protected
verify_urlPublic proof page URL you can share with anyone
statusConfirmation status (protected)
Each protection generates a public proof page. Anyone can fetch the proof page metadata via GET /v1/public/proof/{attestation_id} — no authentication required. This endpoint is designed for rendering proof pages and generating Open Graph link previews for shared URLs. See the proof metadata endpoint for details.

​
Risk signals

A risk signal is a scored observation from a fraud-detection source — device fingerprinting, IP reputation, email verification, document analysis, or your own rules engine. You can ingest signals directly via the API, or submit raw identity events and let the platform normalize them into signals automatically. Each signal includes:
FieldDescription
signal_sourceWhere the signal came from (e.g. device_fingerprint, ip_reputation, login)
signal_typeWhat was detected (e.g. velocity, geo_anomaly, ato, deepfake)
risk_scoreRisk score from 0 (safe) to 100 (high risk) — scores at or above 80 trigger automatic review
subject_idIdentifier of the entity being evaluated
subject_typeThe type of entity: user, issuer, session, device, ip, or attestation
payloadArbitrary metadata (IP addresses, geolocation, reasons)

​
Event normalization

Instead of constructing risk signals manually, you can submit raw identity events — failed logins, invalid signatures, deepfake suspects — to POST /v1/risk/events. The platform maps each event to a canonical signal type and base risk score automatically. See the normalize identity event API reference. Risk signals are fully tenant-isolated using row-level security and form the foundation of the Anti-Fraud Identity Firewall. See the risk signals guide for integration details.

​
Machine agents

A machine agent is an AI agent, bot, or automated service registered with the Machine Agent Identity Protocol (MAIP). Each agent gets a unique identifier (maip-agent:<ulid>) and an Ed25519 keypair for signing receipts.
FieldDescription
agent_idUnique MAIP identifier for the agent
nameHuman-readable agent name (e.g., order-processor)
typeAgent type: autonomous, supervised, delegated, or system
scopesPermission scopes the agent is authorized to use
statusLifecycle status: active, suspended, or revoked
trust_scoreContinuous 0–100 behavioral trust score
Agents operate within sessions — short-lived, scope-bound execution contexts with automatic expiry. Every action an agent takes generates a cryptographically signed receipt that chains to the previous receipt for tamper-evident audit trails. Nine receipt types cover the full agent lifecycle: genesis, delegation, action, revocation, data attestation, model attestation, compliance, truth claim, and verification. See the machine identity guide for setup and the agent authorization guide for the scope and session model.

​
Proof bundles

A proof bundle is a self-contained package that includes everything needed to verify an attestation offline, without contacting Truthlocks servers. 
{
  "attestation": { ... },       // Full attestation object
  "issuer": {
    "id": "uuid",
    "name": "Acme University",
    "domain": "acme.edu",
    "trust_level": "VERIFIED"
  },
  "public_key": {
    "kid": "ed-key-2026",
    "algorithm": "Ed25519",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----..."
  },
  "transparency_proof": {
    "log_index": 42,
    "root_hash": "sha256:...",
    "inclusion_proof": ["hash1", "hash2", ...]
  }
}
Use Case: Proof bundles are ideal for scenarios where verifiers may be offline or want to independently verify without API calls.

​
Verification Model

Truthlocks verification checks multiple layers to determine if an attestation should be trusted:
1

Cryptographic Verification

Verify the Ed25519 signature matches the payload using the issuer’s public key.
2

Status Check

Check if the attestation has been revoked or superseded by the issuer. Superseded attestations link to their replacement via superseded_by_attestation_id.
3

Issuer Trust Status

Confirm the issuer is in ACTIVE status and not suspended.
4

Key Validity

Verify the signing key was active at the time of attestation creation.

​
Next Steps

Environments

Learn about development vs production environments and configuration.

Authentication

Deep dive into API keys, JWT tokens, and OAuth integration.