Core Concepts

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.

Property	Description
`id`	Unique UUID identifying the tenant
`name`	Human-readable organization name
`slug`	URL-safe identifier (e.g., `acme-corp`)
`tier`	Subscription tier: FREE, STARTER, PROFESSIONAL, ENTERPRISE
`status`	ACTIVE, 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

Property	Description
Immutable	Once created, the payload and signature cannot be modified
Revocable	Issuers can revoke attestations, updating status to REVOKED
Supersedable	Issuers can supersede an attestation with a new version, creating an auditable chain while preserving the original
Portable	Attestation ID can be shared and verified anywhere
Auditable	Every 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:

Field	Description
`protection_id`	Unique ID for the protection record
`attestation_id`	The underlying attestation ID (used for verification)
`content_hash`	The SHA-256 hash you submitted, echoed back for confirmation
`protected_at`	Exact timestamp when the content was protected
`verify_url`	Public proof page URL you can share with anyone
`status`	Confirmation 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:

Field	Description
`signal_source`	Where the signal came from (e.g. `device_fingerprint`, `ip_reputation`, `login`)
`signal_type`	What was detected (e.g. `velocity`, `geo_anomaly`, `ato`, `deepfake`)
`risk_score`	Risk score from `0` (safe) to `100` (high risk) — scores at or above 80 trigger automatic review
`subject_id`	Identifier of the entity being evaluated
`subject_type`	The type of entity: `user`, `issuer`, `session`, `device`, `ip`, or `attestation`
`payload`	Arbitrary 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.

Field	Description
`agent_id`	Unique MAIP identifier for the agent
`name`	Human-readable agent name (e.g., `order-processor`)
`type`	Agent type: `autonomous`, `supervised`, `delegated`, or `system`
`scopes`	Permission scopes the agent is authorized to use
`status`	Lifecycle status: `active`, `suspended`, or `revoked`
`trust_score`	Continuous 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:

Cryptographic Verification

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

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.

Issuer Trust Status

Confirm the issuer is in ACTIVE status and not suspended.

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.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

Tenants

Multi-Tenancy Guarantees

Issuers

Identity

Cryptographic Keys

Trust Status

Trust Level

Issuer lifecycle

Attestations

Attestation Structure

Attestation Properties

Consumer protections

Risk signals

Event normalization

Machine agents

Proof bundles

Verification Model

Next Steps

Environments

Authentication

​Tenants

​Multi-Tenancy Guarantees

​Issuers

Identity

Cryptographic Keys

Trust Status

Trust Level

​Issuer lifecycle

​Attestations

​Attestation Structure

​Attestation Properties

​Consumer protections

​Risk signals

​Event normalization

​Machine agents

​Proof bundles

​Verification Model

​Next Steps

Environments

Authentication

Tenants

Multi-Tenancy Guarantees

Issuers

Issuer lifecycle

Attestations

Attestation Structure

Attestation Properties

Consumer protections

Risk signals

Event normalization

Machine agents

Proof bundles

Verification Model

Next Steps