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

# Bestätigung überprüfen

> Überprüfen Sie den Datensatzstatus, die Metadaten des Ausstellers und die verfügbaren Beweise. Geben Sie die exakte ursprüngliche payload_b64url an, um die kryptografische Signatur zu überprüfen. Eine Suche nur nach ID oder nur nach Dateifingerabdruck gibt INCOMPLETE mit signature_verified false zurück, wenn kein schwerwiegenderer Fehler zutrifft. VALID bedeutet, dass die bereitgestellte Nutzlast die Signaturprüfungen bestanden hat; dies beweist nicht die Wahrheit der Behauptungen oder garantiert, dass optionale Richtlinien- und Transparenzprüfungen abgeschlossen wurden. Überprüfen Sie die Gründe und log.proof_checked. Öffentliche Anfragen benötigen keinen API-Schlüssel; authentifizierte Anfragen sind auf den Arbeitsbereich des Aufrufers beschränkt und werden diesem in Rechnung gestellt.

Überprüfen Sie den aktuellen Status eines Datensatzes und die verfügbaren Beweise. Um seine kryptografische Signatur zu überprüfen, senden Sie die **exakte original signierte Nutzlast** als `payload_b64url`. Eine Datensatz-ID oder ein Dateifingerabdruck allein kann diese Bytes nicht liefern.

### Wählen Sie die benötigte Prüfung

| Eingabe | Was es prüft |
| - | - |
| `attestation_id` | Findet einen zugänglichen Datensatz und überprüft dessen aktuellen Status, Aussteller-Metadaten und verfügbare Protokollnachweise. |
| ID plus `payload_b64url` | Überprüft auch den Payload-Digest und die Signatur anhand des registrierten öffentlichen Schlüssels. Codieren Sie die ursprünglichen Bytes; das Neuformatieren von JSON kann diese Bytes ändern. |
| ID plus `document_hash_hex` | Vergleicht einen bereitgestellten SHA-256-Fingerabdruck mit dem aufgezeichneten Dokumenten-Fingerabdruck. Dies ersetzt nicht die Prüfung der signierten Nutzlast. |

Eine reine ID- oder reine Fingerabdruckprüfung gibt `INCOMPLETE` und `signature_verified: false` zurück, es sei denn, ein stärkeres Ergebnis wie `REVOKED`, `EXPIRED` oder `ALTERED` trifft zu. Geben Sie die ursprüngliche Nutzlast für eine vollständige Signaturprüfung an.

Ein Inline-`attestation` muss einen registrierten Datensatz mit `attestation_id` identifizieren. Der Online-Status und die Schlüsselidentität werden aus diesem Datensatz geladen; vom Aufrufer bereitgestellte Felder können dessen Aussteller oder Widerruf nicht überschreiben. Verwenden Sie einen kompatiblen Offline-Verifizierer für eigenständige Signaturprüfungen.

### Die Antwort interpretieren

| Urteil | Bedeutung |
| - | - |
| `VALID` | Die bereitgestellte Nutzlast hat ihre Signaturprüfung bestanden, und es wurde kein blockierender Fehler zurückgegeben. Überprüfen Sie die Gründe und einzelnen Prüfungen. |
| `INCOMPLETE` | Erforderlicher Originalinhalt wurde nicht geliefert; die Signatur wurde nicht geprüft. |
| `ALTERED` | Eine bereitgestellte Nutzlast, Signatur oder ein Dokumenten-Fingerabdruck hat eine Integritätsprüfung nicht bestanden. |
| `REVOKED` | Der Datensatz wurde widerrufen. |
| `SUPERSEDED` | Ein neuerer Datensatz ersetzt diesen. Fragen Sie den Aussteller nach seinem aktuellen Datensatz. |
| `EXPIRED` | Der Datensatz oder der Signaturschlüssel ist abgelaufen. |
| `INVALID` | Eine erforderliche Eingabe- oder Überprüfung fehlgeschlagen. |
| `NOT_FOUND` | Keine zugängliche Aufzeichnung entsprach der Anfrage und ihrer Umgebung. |
| `UNKNOWN_ISSUER` | Der Signaturschlüssel des Ausstellers konnte nicht akzeptiert werden. |

`signature_verified` meldet speziell die Signaturprüfung. `log.proof_checked` meldet die erfolgreiche Überprüfung der Transparenz-Inklusion. Ein fehlender Beweis erzeugt einen Grund und einen Null-Blattindex; Null ist ein legitimes erstes Blatt. Ein fehlender `expires_at_unix`-Wert bedeutet nicht, dass ein neues Ablaufdatum für einen historischen Datensatz erfunden werden sollte.

> [!WARNING]
>
> Eine gültige Signatur beweist nicht Eigentum, rechtliche Gültigkeit oder die Wahrheit jeder Behauptung. Lesen Sie `reasons`, die aktuelle Issuer-Governance und die verfügbaren Beweise, bevor Sie sich auf einen Datensatz verlassen. Optionale Richtlinien- oder Protokollprüfungen können auch dann nicht verfügbar sein, wenn die Payload-Signatur erfolgreich ist.

### Authentifizierung und Limits

Die öffentliche Verifizierung erfordert keinen API-Schlüssel. Authentifizierte Aufrufe verwenden den Arbeitsbereich und die Umgebung des Anrufers und können dessen Verifizierungsfreigabe unterliegen. Dienst-Ratenbegrenzungen gelten weiterhin für öffentliche Anfragen. Ein privater oder Sandbox-Datensatz ist möglicherweise nicht über eine anonyme Produktionssuche verfügbar.

Teilen Sie einen zugänglichen Datensatz mit `https://verify.truthlocks.com/proof/{attestation_id}`. Eine geteilte URL gewährt keinen Zugriff auf private Nutzdaten.


## OpenAPI

````yaml de/mint-openapi.yaml POST /v1/verify
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks ist eine universelle Verifizierungsinfrastruktur für Dokumente,
    Anmeldeinformationen und digitale Assets.

    Diese Spezifikation definiert die kanonische API für die Interaktion mit
    Truthlocks-Diensten.


    ## Basis-URLs

    - **Produktion**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentifizierung

    - **API-Schlüssel**: Verwenden Sie den Header `X-API-Key` für
    Machine-to-Machine-Operationen

    - **Bearer Tokens**: Verwenden Sie `Authorization: Bearer <jwt>` für
    benutzerinitiierte Operationen


    ## Mandantenidentität

    In der Produktion wird die Mandantenidentität aus dem authentifizierten
    Kontext (API-Schlüssel oder JWT) abgeleitet.

    Der Header `X-Tenant-ID` wird in der Produktion ignoriert, um Spoofing zu
    verhindern.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Produktions-API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox-Umgebung
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: API-Schlüssel- und Token-Verwaltung
  - name: Issuers
    description: Ausstellerregistrierung und Vertrauensmanagement
  - name: Keys
    description: Kryptographische Schlüsselverwaltung für Aussteller
  - name: Attestations
    description: Bestätigungslebenszyklus (prägen, widerrufen, ersetzen)
  - name: Verification
    description: Bestätigungsverifizierung und Proof-Bundles
  - name: Governance
    description: Aussteller-Governance-Workflows (nur Admin)
  - name: Identity
    description: Organisations-, Benutzer- und Rollenverwaltung
  - name: Audit
    description: Audit-Ereignisabfragen
  - name: Tenant Console
    description: Mandantenprofil- und Lebenszyklus-Endpunkte
  - name: Health
    description: Endpunkte für Dienststatus und Bereitschaft
  - name: Risk
    description: Erfassung von Risikosignalen und Betrugserkennung
  - name: Risk Enforcement
    description: >-
      Risikodurchsetzungsmaßnahmen – Blockieren, Herausfordern, Quarantäne und
      Konfiguration
  - name: Billing
    description: Verwaltung von Abrechnung, Abonnements und Add-ons
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) – Agentenregistrierung, Sitzungen,
      Vertrauen, Zeugen, Compliance, Orchestrierung und Beobachtbarkeit
externalDocs:
  description: Transparenz-API nur lesend (separate Dienstspezifikation)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/verify:
    post:
      tags:
        - Verification
      summary: Bestätigung überprüfen
      description: >-
        Überprüfen Sie den Datensatzstatus, die Metadaten des Ausstellers und
        die verfügbaren Beweise. Geben Sie die exakte ursprüngliche
        payload_b64url an, um die kryptografische Signatur zu überprüfen. Eine
        Suche nur nach ID oder nur nach Dateifingerabdruck gibt INCOMPLETE mit
        signature_verified false zurück, wenn kein schwerwiegenderer Fehler
        zutrifft. VALID bedeutet, dass die bereitgestellte Nutzlast die
        Signaturprüfungen bestanden hat; dies beweist nicht die Wahrheit der
        Behauptungen oder garantiert, dass optionale Richtlinien- und
        Transparenzprüfungen abgeschlossen wurden. Überprüfen Sie die Gründe und
        log.proof_checked. Öffentliche Anfragen benötigen keinen API-Schlüssel;
        authentifizierte Anfragen sind auf den Arbeitsbereich des Aufrufers
        beschränkt und werden diesem in Rechnung gestellt.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                attestation:
                  description: >-
                    Online-Nachschlage-Umschlag. Eine registrierte
                    attestation_id ist hier oder auf Anforderungsebene
                    erforderlich. Der gespeicherte Status, Aussteller, Schlüssel
                    und Ausstellungszeitpunkt sind maßgeblich; bereitgestellte
                    Kopien können diese nicht überschreiben.
                  nullable: true
                  properties:
                    attestation_id:
                      type: string
                    document_hash:
                      type: string
                    expires_at_unix:
                      type: integer
                      format: int64
                      nullable: true
                      description: >-
                        Aufgezeichneter signierter Ablauf in Unix-Sekunden; null
                        bedeutet, dass kein Ablauf aufgezeichnet wird. Älteren
                        Datensätzen wird kein neuer Ablauf zugewiesen.
                    issued_at_unix:
                      type: integer
                    issuer_id:
                      type: string
                    log:
                      type: object
                      properties:
                        log_id:
                          type: string
                        leaf_index:
                          type: integer
                          nullable: true
                          description: >-
                            Nullbasierter Transparenz-Blattindex. Null bedeutet,
                            dass die Log-Referenz nicht wiederhergestellt werden
                            konnte; Null ist ein gültiger erster Eintrag.
                        status:
                          type: string
                          enum:
                            - recorded
                            - unavailable
                          description: >-
                            Verfügbarkeit des gespeicherten Log-Referenz; dies
                            begründet kein verifiziertes Inklusionsurteil.
                        leaf_hash:
                          type: string
                        proof_url:
                          type: string
                    payload_hash:
                      type: string
                    signature:
                      type: object
                      properties:
                        alg:
                          type: string
                        kid:
                          type: string
                        value:
                          type: string
                    status:
                      type: string
                    tenant_id:
                      type: string
                      format: uuid
                    version:
                      type: string
                  type: object
                attestation_id:
                  type: string
                document_hash_hex:
                  type: string
                payload_b64url:
                  type: string
              type: object
      responses:
        '200':
          description: Verifizierungsergebnis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              examples:
                valid:
                  summary: Valid attestation
                  value:
                    verdict: VALID
                    valid: true
                    details:
                      issuer_id: 550e8400-e29b-41d4-a716-446655440000
                      issuer_name: Acme University
                      log_index: 42
                revoked:
                  summary: Revoked attestation
                  value:
                    verdict: REVOKED
                    valid: false
                    details:
                      revoked_at: '2026-01-13T15:00:00.000Z'
                      reason: Certificate holder no longer employed
      security:
        - APIKey: []
        - {}
components:
  schemas:
    VerifyResponse:
      type: object
      required:
        - verdict
      description: >-
        Öffentliche Verifizierungsnachweise. Überprüfen Sie Gründe und einzelne
        Prüfungen; eine reine ID-Prüfung verifiziert nicht den vom Anrufer
        bereitgestellten Originalinhalt.
      properties:
        verdict:
          $ref: '#/components/schemas/Verdict'
        signature_verified:
          type: boolean
          description: >-
            Nur wahr, wenn die bereitgestellte ursprüngliche Nutzlast die
            kryptografische Signaturprüfung bestanden hat. Nur-ID- und
            Nur-Fingerabdruck-Prüfungen geben false zurück.
        reasons:
          type: array
          items:
            type: string
        attestation_id:
          type: string
          format: uuid
        issuer_id:
          type: string
          format: uuid
        expires_at_unix:
          type: integer
          format: int64
          nullable: true
          description: >-
            Aufgezeichneter signierter Ablauf in Unix-Sekunden; null bedeutet,
            dass kein Ablauf aufgezeichnet wird. Älteren Datensätzen wird kein
            neuer Ablauf zugewiesen.
        issued_at_unix:
          type: integer
          format: int64
          description: >-
            Ursprüngliche gespeicherte Ausstellungszeit in Unix-Sekunden. Dies
            ist nicht die Zeit der aktuellen Prüfung oder des
            Zertifikatsdownloads. Fehlt, wenn nicht verfügbar.
        kid:
          type: string
          description: Signaturschlüssel-ID.
        alg:
          type: string
          description: Deklarierter Signaturalgorithmus.
        payload_hash:
          type: string
          description: Base64url-kodierter SHA-256-Digest der kanonischen Nutzlast.
        document_hash:
          type: string
          description: >-
            Hexadezimaler SHA-256-Fingerabdruck der Originaldatei, wenn
            gespeichert.
        log:
          type: object
          properties:
            log_id:
              type: string
            leaf_index:
              type: integer
              format: int64
              nullable: true
              description: >-
                Verifizierter Transparenzblattindex; null, wenn die
                Proof-Verifizierung nicht verfügbar war. Null ist ein gültiges
                erstes Blatt.
            leaf_hash:
              type: string
              description: Verifizierter Inklusionsblatt-Digest, falls verfügbar.
            proof_checked:
              type: boolean
              description: >-
                Ob die Transparenz-Inklusion für diese Antwort erfolgreich
                überprüft wurde.
        governance:
          type: object
          properties:
            issuer_display_name:
              type: string
            issuer_status:
              type: string
            issuer_trust_tier:
              type: string
            issuer_risk_rating:
              type: string
            issuer_jurisdiction:
              type: string
            primary_color:
              type: string
            accent_color:
              type: string
            logo_url:
              type: string
            snapshot_status:
              type: string
            snapshot_trust_tier:
              type: string
            snapshot_risk_rating:
              type: string
            snapshot_jurisdiction:
              type: string
    Verdict:
      type: string
      enum:
        - VALID
        - INCOMPLETE
        - INVALID
        - REVOKED
        - ALTERED
        - SUPERSEDED
        - EXPIRED
        - UNKNOWN_ISSUER
        - NOT_FOUND
      description: >-
        Überprüfen Sie die Gründe, die bereitgestellten Verifizierungseingaben
        und log.proof_checked zusammen mit diesem Urteil. VALID allein begründet
        weder den Besitz noch beweist es jede Behauptung im Datensatz.
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API-Schlüssel für die Maschine-zu-Maschine-Authentifizierung
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT für benutzerinitiierte Operationen

````

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