> ## 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.
# Core Concepts
> Understanding tenants, issuers, attestations, and verification.
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.
Each issuer has a verified domain (e.g., `acme.edu`) that establishes their
real-world identity.
Issuers register Ed25519 public keys used to verify attestation signatures.
New issuers are activated immediately on creation. Higher trust tiers require an application review: ACTIVE → SUSPENDED.
BASIC, VERIFIED, or PREMIUM based on identity verification depth.
### Issuer lifecycle
```text theme={null}
┌──────────────┐
│ 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](/guides/issuer-applications) 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
```json theme={null}
{
"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](/api-reference/attestations/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](/api-reference/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](/api-reference/consumer/proof-metadata) 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](/api-reference/risk/normalize-event).
Risk signals are fully tenant-isolated using [row-level security](/security/rls) and form the foundation of the Anti-Fraud Identity Firewall. See the [risk signals guide](/guides/risk-signals) for integration details.
## Machine agents
A **machine agent** is an AI agent, bot, or automated service registered with the [Machine Agent Identity Protocol (MAIP)](/guides/machine-identity). Each agent gets a unique identifier (`maip-agent:`) 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](/guides/machine-identity) for setup and the [agent authorization guide](/guides/agent-authorization) 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.
```json theme={null}
{
"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:
Verify the Ed25519 signature matches the payload using the issuer's public
key.
Check if the attestation has been revoked or superseded by the issuer. Superseded attestations link to their replacement via `superseded_by_attestation_id`.
Confirm the issuer is in ACTIVE status and not suspended.
Verify the signing key was active at the time of attestation creation.
## Next Steps
Learn about development vs production environments and configuration.
Deep dive into API keys, JWT tokens, and OAuth integration.