Core Concepts
This guide explains the fundamental building blocks of the Truthlock platform. Understanding these concepts is essential for effective integration.
Tenants
A tenant is the top-level organizational unit in Truthlock. 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
Issuers go through a governance lifecycle: PENDING → APPROVED → SUSPENDED.
Trust Level
BASIC, VERIFIED, or PREMIUM based on identity verification depth.
Issuer Lifecycle
┌──────────────┐
│ CREATED │
└───────┬──────┘
│
▼
┌──────────────┐
│ PENDING │ ← Awaiting governance approval
└───────┬──────┘
approve │ │ reject
▼ ▼
┌──────────────┐ ┌──────────────┐
│ APPROVED │ │ REJECTED │
└───────┬──────┘ └──────────────┘
│
suspend │ reinstate
▼
┌──────────────┐
│ SUSPENDED │
└──────────────┘Attestations
An attestation is a cryptographically signed claim made by an issuer about a subject. Attestations are the core primitive of the Truthlock 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 |
| Portable | Attestation ID can be shared and verified anywhere |
| Auditable | Every operation is logged in the transparency log |
Proof Bundles
A proof bundle is a self-contained package that includes everything needed to verify an attestation offline, without contacting Truthlock 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", ...]
}
}Verification Model
Truthlock 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. Revocation Check
Check if the attestation has been revoked by the issuer.
3. Issuer Trust Status
Confirm the issuer is in APPROVED status and not suspended.
4. Key Validity
Verify the signing key was active at the time of attestation creation.