> ## 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.

# Kernkonzepte

> Verständnis von Mandanten, Ausstellern, Bestätigungen und Verifizierung.

Dieser Leitfaden erläutert die grundlegenden Bausteine der Truthlocks-Plattform. Das Verständnis dieser Konzepte ist für eine effektive Integration unerlässlich.

## Mandanten

Ein **Mandant** ist die oberste Organisationseinheit in Truthlocks. Jeder Mandant repräsentiert einen eigenen Kunden oder eine Organisation mit vollständiger Datenisolation.

| Eigenschaft | Beschreibung |
| - | - |
| `id` | Eindeutige UUID zur Identifizierung des Mandanten |
| `name` | Menschlich lesbarer Organisationsname |
| `slug` | URL-sicherer Bezeichner (z.B. `acme-corp`) |
| `tier` | Abonnementstufe: FREE, STARTER, PROFESSIONAL, ENTERPRISE |
| `status` | AKTIV, AUSGESETZT oder GELÖSCHT |

### Mandantenfähigkeitskontrollen

* **Datenisolation:** Die Daten jedes Mandanten sind auf Datenbankebene vollständig isoliert
* **Ressourcenlimits:** Ratenbegrenzungen und Kontingente werden pro Mandant durchgesetzt
* **API-Schlüssel-Bereich:** API-Schlüssel sind an einen einzelnen Mandanten gebunden und können nicht auf Daten anderer Mandanten zugreifen.
* **Audit-Trennung:** Audit-Protokolle sind nach Mandanten partitioniert.

## Aussteller

Ein **Aussteller** ist eine Entität, die Bestätigungen erstellen und signieren kann. Aussteller repräsentieren Organisationen, Institutionen oder Dienste, die Ansprüche über Subjekte erheben.

> [card] Identität
>
> Jeder Aussteller hat eine verifizierte Domain (z. B. `acme.edu`), die seine Identität festlegt.
> reale Identität.

> [card] Kryptografische Schlüssel
>
> Aussteller registrieren Ed25519-öffentliche Schlüssel, die zur Überprüfung von Bestätigungsunterschriften verwendet werden.

> [card] Vertrauensstatus
>
> Neue Aussteller werden sofort nach der Erstellung aktiviert. Höhere Vertrauensstufen erfordern eine Anwendungsprüfung: AKTIV → AUSGESETZT.

> [card] Vertrauensstufe
>
> BASIC, VERIFIED oder PREMIUM basierend auf der Tiefe der Identitätsprüfung.

### Aussteller-Lebenszyklus

```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)│
                      └──────────────┘  └──────────────┘
```

> [!NOTE]
>
> Neue Aussteller werden sofort mit dem Vertrauensniveau **Basic** aktiviert. Es ist keine manuelle Genehmigung erforderlich, um mit der Prägung von Bestätigungen zu beginnen. Um auf eine höhere Vertrauensstufe (Verifizierte Organisation, Regierungseinheit oder Akkreditierte Institution) aufzusteigen, reichen Sie einen [Ausstellerantrag](https://docs.truthlocks.com/de/guides/issuer-applications.md) zur Überprüfung ein.

## Bestätigungen

Eine **Bestätigung** ist ein kryptografisch signierter Anspruch, der von einem Aussteller über ein Subjekt gemacht wird. Bestätigungen sind das Kernprimitiv des Truthlocks-Systems.

### Attestierungsstruktur

```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"
}
```

### Attestierungseigenschaften

| Eigenschaft | Beschreibung |
| - | - |
| **Unveränderlich** | Nach der Erstellung können Nutzlast und Signatur nicht mehr geändert werden |
| **Widerrufbar** | Aussteller können Bestätigungen widerrufen und den Status auf WIDERRUFEN aktualisieren |
| **Ersetzbar** | Aussteller können eine Bescheinigung durch eine neue Version [ersetzen](https://docs.truthlocks.com/de/api-reference/attestations/supersede.md), wodurch eine nachvollziehbare Kette entsteht, während das Original erhalten bleibt |
| **Portabel** | Die Bestätigungs-ID kann überall geteilt und verifiziert werden |
| **Auditierbar** | Jeder Vorgang wird im Transparenzprotokoll protokolliert |

## Verbraucherschutz

Ein **Verbraucherschutz** ist eine Bestätigung, die über den vereinfachten [consumer mint](https://docs.truthlocks.com/de/api-reference/consumer/mint.md)-Flow erstellt wird und für einzelne Ersteller konzipiert ist. Sie hashen Ihre Datei clientseitig (SHA-256) und übermitteln den Hash zusammen mit Metadaten wie Titel, Kategorie und Inhaltstyp. Truthlocks stellt Ihre Signaturidentität bei der ersten Verwendung automatisch bereit.

Die Antwort des Verbraucher-Mint enthält:

| Feld | Beschreibung |
| - | - |
| `protection_id` | Eindeutige ID für den Schutzdatensatz |
| `attestation_id` | Die zugrunde liegende Attestierungs-ID (wird zur Verifizierung verwendet) |
| `content_hash` | Der von Ihnen übermittelte SHA-256-Hash, zur Bestätigung zurückgegeben |
| `protected_at` | Exakter Zeitstempel, wann der Inhalt geschützt wurde |
| `verify_url` | Öffentliche Proof-Seiten-URL, die Sie mit jedem teilen können |
| `status` | Bestätigungsstatus (`protected`) |

Jeder Schutz generiert eine öffentliche Nachweisseite. Jeder kann die Metadaten der Nachweisseite über `GET /v1/public/proof/{attestation_id}` abrufen – keine Authentifizierung erforderlich. Dieser Endpunkt ist für das Rendern von Nachweisseiten und das Generieren von Open Graph-Linkvorschauen für geteilte URLs konzipiert. Details finden Sie unter [Nachweis-Metadaten-Endpunkt](https://docs.truthlocks.com/de/api-reference/consumer/proof-metadata.md).

## Risikosignale

Ein **Risikosignal** ist eine bewertete Beobachtung aus einer Betrugserkennungsquelle – Geräte-Fingerprinting, IP-Reputation, E-Mail-Verifizierung, Dokumentenanalyse oder Ihre eigene Regel-Engine. Sie können Signale direkt über die API aufnehmen oder Rohdaten von Identitätsereignissen übermitteln und die Plattform diese automatisch in Signale normalisieren lassen.

Jedes Signal beinhaltet:

| Feld | Beschreibung |
| :- | :- |
| `signal_source` | Woher das Signal kam (z. B. `device_fingerprint`, `ip_reputation`, `login`) |
| `signal_type` | Was erkannt wurde (z. B. `velocity`, `geo_anomaly`, `ato`, `deepfake`) |
| `risk_score` | Risikobewertung von `0` (sicher) bis `100` (hohes Risiko) – Bewertungen ab 80 lösen eine automatische Überprüfung aus |
| `subject_id` | Kennung der zu bewertenden Entität |
| `subject_type` | Der Entitätstyp: `user`, `issuer`, `session`, `device`, `ip` oder `attestation` |
| `payload` | Beliebige Metadaten (IP-Adressen, Geolokalisierung, Gründe) |

### Ereignisnormalisierung

Anstatt Risikosignale manuell zu konstruieren, können Sie Rohdaten von Identitätsereignissen – fehlgeschlagene Anmeldungen, ungültige Signaturen, Deepfake-Verdächtige – an `POST /v1/risk/events` übermitteln. Die Plattform ordnet jedes Ereignis automatisch einem kanonischen Signaltyp und einem Basis-Risikowert zu. Siehe die [API-Referenz zur Normalisierung von Identitätsereignissen](https://docs.truthlocks.com/de/api-reference/risk/normalize-event.md).

Risikosignale sind vollständig mandantenisoliert unter Verwendung von [Row-Level Security](https://docs.truthlocks.com/de/security/rls.md) und bilden die Grundlage der Anti-Fraud Identity Firewall. Details zur Integration finden Sie im [Risikosignal-Leitfaden](https://docs.truthlocks.com/de/guides/risk-signals.md).

## Maschinenagenten

Ein **Maschinenagent** ist ein KI-Agent, Bot oder automatisierter Dienst, der beim [Machine Agent Identity Protocol (MAIP)](https://docs.truthlocks.com/de/guides/machine-identity.md) registriert ist. Jeder Agent erhält eine eindeutige Kennung (`maip-agent:<ulid>`) und ein Ed25519-Schlüsselpaar zum Signieren von Belegen.

| Feld | Beschreibung |
| :- | :- |
| `agent_id` | Eindeutige MAIP-Kennung für den Agenten |
| `name` | Menschenlesbarer Agentenname (z. B. `order-processor`) |
| `type` | Agententyp: `autonomous`, `supervised`, `delegated` oder `system` |
| `scopes` | Berechtigungsumfänge, die der Agent verwenden darf |
| `status` | Lebenszyklusstatus: `active`, `suspended` oder `revoked` |
| `trust_score` | Kontinuierlicher Verhaltens-Vertrauenswert von 0–100 |

Agenten agieren innerhalb von **Sitzungen** – kurzlebigen, bereichsgebundenen Ausführungskontexten mit automatischem Ablauf. Jede Aktion, die ein Agent ausführt, erzeugt einen kryptografisch signierten **Beleg**, der an den vorherigen Beleg gekettet ist, um manipulationssichere Prüfprotokolle zu gewährleisten. Neun Belegtypen decken den gesamten Agentenlebenszyklus ab: Genesis, Delegation, Aktion, Widerruf, Datenbestätigung, Modellbestätigung, Compliance, Wahrheitsanspruch und Verifizierung.

Informationen zur Einrichtung finden Sie im [Handbuch zur Maschinenidentität](https://docs.truthlocks.com/de/guides/machine-identity.md) und zum Bereichs- und Sitzungsmodell im [Handbuch zur Agentenautorisierung](https://docs.truthlocks.com/de/guides/agent-authorization.md).

## Proof-Bundles

Ein **Proof Bundle** ist ein eigenständiges Paket, das alles enthält, was zur Offline-Verifizierung einer Bestätigung erforderlich ist, ohne Truthlocks-Server zu kontaktieren.

```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", ...]
  }
}
```

> [!NOTE]
>
> **Anwendungsfall:** Proof-Bundles sind ideal für Szenarien, in denen Prüfer möglicherweise
> offline oder möchten unabhängig ohne API-Aufrufe verifizieren.

## Verifizierungsmodell

Die Truthlocks-Verifizierung prüft mehrere Ebenen, um festzustellen, ob eine Bestätigung vertrauenswürdig sein sollte:

**1. Kryptografische Verifizierung**

Verifizieren Sie, dass die Ed25519-Signatur mit der Nutzlast übereinstimmt, indem Sie den öffentlichen Schlüssel des Ausstellers verwenden
Schlüssel.

**2. Statusprüfung**

Prüfen Sie, ob die Bestätigung vom Aussteller widerrufen oder ersetzt wurde. Ersetzte Bestätigungen verweisen über `superseded_by_attestation_id` auf ihren Ersatz.

**3. Vertrauensstatus des Ausstellers**

Bestätigen Sie, dass der Aussteller den Status AKTIV hat und nicht gesperrt ist.

**4. Schlüsselgültigkeit**

Verifizieren Sie, dass der Signaturschlüssel zum Zeitpunkt der Attestierungserstellung aktiv war.

## Nächste Schritte

> [card] [Umgebungen](https://docs.truthlocks.com/environments.md)
>
> Erfahren Sie mehr über Entwicklungs- und Produktionsumgebungen und deren Konfiguration.

> [card] [Authentifizierung](https://docs.truthlocks.com/security/auth.md)
>
> Tiefer Einblick in API-Schlüssel, JWT-Tokens und OAuth-Integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.