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

# Audit-Protokolle

> Verfolgen Sie alle API-Aktivitäten, Sicherheitsereignisse und Compliance-Audits.

Truthlocks führt umfassende Audit-Protokolle für die Sicherheitsüberwachung, Compliance-Berichterstattung und operative Fehlerbehebung.

## Was protokolliert wird

Jede API-Operation generiert ein Audit-Ereignis. Dies umfasst erfolgreiche Operationen, fehlgeschlagene Versuche und sicherheitsrelevante Ereignisse.

> [card] API-Operationen
>
> * Attestierung prägen \* Attestierung widerrufen \* Aussteller
>   Erstellung/Änderung \* Schlüsselregistrierung

> [card] Sicherheitsereignisse
>
> * Authentifizierungsfehler \* Berechtigung verweigert \* Ratenlimit überschritten \*
>   Verdächtige Aktivität

> [card] Governance-Aktionen
>
> * Ausstellergenehmigung/-ablehnung \* Aussetzungsverfahren für Aussteller \* Rollenzuweisungen \* API-Schlüssel
>   Verwaltung

> [card] Benutzeraktivität
>
> * Benutzeranmeldung/-abmeldung \* Passwortänderungen \* Benutzereinladungen \* Rollenänderungen

## Struktur des Audit-Ereignisses

Jedes Audit-Ereignis enthält detaillierten Kontext darüber, was passiert ist, wer es getan hat und wann:

```json theme={null}
{
  "id": "evt_abc123",
  "timestamp": "2026-01-13T12:34:56.789Z",
  "tenant_id": "tenant-uuid",
  "actor_type": "USER",
  "actor_id": "user-uuid",
  "action": "attestation.mint",
  "resource_type": "attestation",
  "resource_id": "attestation-uuid",
  "service": "trust-registry",
  "outcome": "SUCCESS",
  "metadata": {
    "issuer_id": "issuer-uuid",
    "subject": "user:12345",
    "claim": "email_verified"
  },
  "integrity_hash": "sha256:abc123..."
}
```

| Feld | Typ | Beschreibung |
| - | - | - |
| `actor_type` | string | Wer die Aktion durchgeführt hat: `USER`, `API_KEY` oder `SERVICE` |
| `actor_id` | string | UUID des Benutzers, API-Schlüssels oder Dienstes, der das Ereignis ausgelöst hat |
| `action` | string | Die durchgeführte Operation (z. B. `attestation.mint`) |
| `resource_type` | string | Typ der betroffenen Ressource (z.B. `attestation`, `issuer`, `user`) |
| `resource_id` | string | UUID der betroffenen Ressource |
| `service` | string | Der Backend-Dienst, der die Anfrage bearbeitet hat (z. B. `trust-registry`, `audit-service`) |
| `outcome` | string | `SUCCESS` oder `FAILURE` |
| `metadata` | object | Aktion-spezifischer Kontext wie Aussteller-ID, Anspruchstyp oder Fehlerdetails |
| `integrity_hash` | string | SHA-256-Hash zur Überprüfung der Manipulationssicherheit |

## Audit-Logs abfragen

### Grundlegende Abfrage

```bash theme={null}
curl -X GET "https://api.truthlocks.com/v1/audit/events?limit=100" \
  -H "X-API-Key: tl_live_your_api_key"
```

### Gefilterte Abfrage

```bash theme={null}
curl -X GET "https://api.truthlocks.com/v1/audit/events" \
  -H "X-API-Key: tl_live_your_api_key" \
  -G \
  --data-urlencode "action=attestation.mint" \
  --data-urlencode "actor_id=user-uuid" \
  --data-urlencode "from=2026-01-01T00:00:00Z" \
  --data-urlencode "to=2026-01-31T23:59:59Z" \
  --data-urlencode "limit=50"
```

### Filterparameter

| Parameter | Typ | Beschreibung |
| - | - | - |
| `action` | string | Nach Aktionstyp filtern (z. B. `attestation.mint`) |
| `actor_id` | string | Nach Benutzer- oder API-Schlüssel-ID filtern |
| `resource_type` | string | Nach Ressource filtern (Bestätigung, Aussteller, Benutzer) |
| `from` | datetime | Ereignisse nach dieser Zeit (ISO 8601) |
| `to` | datetime | Ereignisse vor dieser Zeit (ISO 8601) |
| `limit` | integer | Maximale Anzahl der zurückzugebenden Ereignisse (Standard 50, maximal 1000) |
| `cursor` | string | Paginierungscursor für die nächste Seite |

## Audit-Trail für Richtlinienentscheidungen

Jede [Ausstellungsrichtlinien](https://docs.truthlocks.com/de/guides/issuance-policies.md)-Bewertung wird automatisch als Audit-Ereignis aufgezeichnet. Jeder Datensatz erfasst die `decision_id`, Richtlinienversion, übereinstimmende Regeln, Bewertungszeit und einen SHA-256-Hash der Eingabe zur Manipulationssicherheit. Abfragen von Richtlinienentscheidungen durch Filtern nach `resource_type=policy_decision`:

```bash theme={null}
curl "https://api.truthlocks.com/v1/audit/events?resource_type=policy_decision&resource_id=dec_7f3a1b" \
  -H "X-API-Key: tl_live_..."
```

Eine vollständige Liste der aufgezeichneten Felder finden Sie unter [Entscheidungs-Audit-Trail](https://docs.truthlocks.com/de/guides/issuance-policies.md#decision-audit-trail).

## Häufige Anwendungsfälle

### Sicherheitsuntersuchung

Alle fehlgeschlagenen Authentifizierungsversuche für einen bestimmten Akteur finden:

```http theme={null}
GET /v1/audit/events
  ?action=auth.failure
  &actor_id=user-uuid
  &from=2026-01-12T00:00:00Z
```

### Compliance-Bericht

Alle Attestierungsoperationen für einen Zeitraum exportieren:

```http theme={null}
GET /v1/audit/events
  ?resource_type=attestation
  &from=2026-01-01T00:00:00Z
  &to=2026-01-31T23:59:59Z
  &limit=1000
```

### Überprüfung der Benutzeraktivität

Sehen Sie alles, was ein bestimmter Benutzer getan hat:

```http theme={null}
GET /v1/audit/events
  ?actor_id=employee-uuid
  &limit=100
```

## Protokollaufbewahrung

| Stufe | Standardaufbewahrung | Exportformat |
| - | - | - |
| Kostenlos | 7 Tage | Nur JSON |
| Starter | 30 Tage | JSON, CSV |
| Professionell | 90 Tage | JSON, CSV, SIEM-Integration |
| Enterprise | 1 Jahr (benutzerdefiniert verfügbar) | Alle Formate + Echtzeit-Streaming |

> [!NOTE]
>
> Für Compliance-Anforderungen, die über Ihre Stufe hinausgehen
> Aufbewahrungsfrist, konfigurieren Sie die SIEM-Integration, um Protokolle an Ihr eigenes System zu streamen.
> Infrastruktur.

### Benutzerdefinierte Aufbewahrungsrichtlinien

Sie können konfigurieren, wie lange Audit-Logs aufbewahrt werden und ob abgelaufene Logs archiviert oder dauerhaft gelöscht werden. Legen Sie Aufbewahrungsrichtlinien global oder pro Umgebung fest.

| Feld | Typ | Beschreibung |
| :- | :- | :- |
| `retention_days` | integer | Tage, an denen Audit-Protokolle aufbewahrt werden sollen (30–3.650) |
| `hard_delete` | boolean | Wenn `true`, abgelaufene Protokolle dauerhaft löschen. Wenn `false`, archivieren. |
| `export_allowed` | boolean | Ob Audit-Exporte für diesen Bereich zulässig sind |
| `environment_id` | string | Optional. Diese Richtlinie nur auf eine bestimmte Umgebung anwenden. |

Die Standardrichtlinie behält Protokolle 365 Tage lang, archiviert (löscht sanft) abgelaufene Protokolle und erlaubt Exporte.

**Rufen Sie Ihre aktuelle Aufbewahrungsrichtlinie ab:**

```bash theme={null}
curl https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "retention_days": 365,
  "hard_delete": false,
  "export_allowed": true,
  "environment_id": null
}
```

**Aufbewahrungsrichtlinie aktualisieren:**

```bash theme={null}
curl -X PUT https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "retention_days": 730,
    "hard_delete": false,
    "export_allowed": true
  }'
```

Wenn eine umgebungsspezifische Richtlinie existiert, hat sie Vorrang vor der globalen Richtlinie. Wenn keine umgebungsspezifische Richtlinie festgelegt ist, gilt die globale Richtlinie.

> [!WARNING]
>
> Das Ändern von `hard_delete` in `true` entfernt Protokolle dauerhaft, sobald sie das Aufbewahrungsfenster überschreiten. Diese Aktion kann nicht rückgängig gemacht werden. Stellen Sie sicher, dass Sie alle benötigten Protokolle exportiert haben, bevor Sie die endgültige Löschung aktivieren.

Das Aktualisieren von Aufbewahrungseinstellungen erfordert die Berechtigung `tenant.audit.retention.manage`. Das Anzeigen von Einstellungen erfordert `tenant.audit.retention.read`.

## SIEM-Integration

Unternehmenskunden können Audit-Logs in Echtzeit an externe Sicherheitsinformations- und Ereignismanagement-Systeme (SIEM) streamen.

### Unterstützte Anbieter

| Anbieter | Transport | Format |
| :- | :- | :- |
| **Splunk** | HTTP Event Collector (HEC) | JSON |
| **Datadog** | Log Management API | JSON |
| **AWS CloudWatch** | Protokollabonnement | JSON |
| **Elastic/ELK** | Elasticsearch-Ingest | JSON |
| **Benutzerdefinierter Webhook** | HTTP POST | JSON |

Konfigurieren Sie ein Streaming-Ziel unter **Einstellungen > Audit > SIEM** in der Konsole oder verwalten Sie Ziele programmatisch über die [SIEM-Konfigurations-API](https://docs.truthlocks.com/de/api-reference/audit/siem/create.md). Schritt-für-Schritt-Anleitungen zur Einrichtung des Anbieters finden Sie im [SIEM-Integrationshandbuch](https://docs.truthlocks.com/de/guides/siem-integration.md).

### Erstellen eines SIEM-Ziels

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "splunk",
    "endpoint": "https://hec.splunk.example.com:8088/services/collector",
    "token": "your-hec-token",
    "enabled": true
  }'
```

```json theme={null}
{
  "id": "siem_abc123",
  "provider": "splunk",
  "endpoint": "https://hec.splunk.example.com:8088/services/collector",
  "enabled": true,
  "created_at": "2026-06-30T12:00:00Z",
  "status": "active"
}
```

Ersetzen Sie `provider` durch eines von `splunk`, `datadog`, `cloudwatch`, `elastic` oder `webhook`. Jeder Anbieter erfordert ein Ziel `endpoint` und ein Authentifizierungs-Credential (`token` für Splunk, Datadog und Elastic; `access_key_id` und `secret_access_key` für CloudWatch; `secret` für benutzerdefinierte Webhooks).

### SIEM-Ziele auflisten

Rufen Sie alle konfigurierten Streaming-Ziele für Ihren Mandanten ab.

```bash theme={null}
curl https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..."
```

### Ein SIEM-Ziel aktualisieren

Ändern Sie den Endpunkt, die Anmeldeinformationen oder den aktivierten Status eines bestehenden Ziels.

```bash theme={null}
curl -X PUT https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://hec-new.splunk.example.com:8088/services/collector",
    "token": "your-new-hec-token",
    "enabled": true
  }'
```

### Löschen eines SIEM-Ziels

Ein Streaming-Ziel entfernen. Laufende Ereignisse werden geleert, bevor das Ziel gelöscht wird.

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..."
```

### Lieferung und Pufferung

Nach der Aktivierung wird jedes Audit-Ereignis in Echtzeit zusammen mit dem standardmäßigen In-Plattform-Protokoll an Ihr Ziel gestreamt. Wenn das Ziel nicht erreichbar ist, werden Ereignisse gepuffert und mit exponentiellem Backoff bis zu 24 Stunden lang erneut versucht. Sie können den Zustellungsstatus im Feld `status` überwachen, das vom Listenendpunkt zurückgegeben wird – mögliche Werte sind `active`, `degraded` (Wiederholung) und `failed`.

> [!WARNING]
>
> **Enterprise-Funktion:** Echtzeit-Log-Streaming erfordert die Enterprise-Stufe.
> Kontaktieren Sie den Vertrieb für Unterstützung bei der Einrichtung.

## Nächste Schritte

> [card] [SIEM-Integration](https://docs.truthlocks.com/guides/siem-integration.md)
>
> Streamen Sie Audit-Ereignisse an Splunk, Datadog, CloudWatch, Elastic oder einen benutzerdefinierten Webhook.

> [card] [Compliance-Exporte](https://docs.truthlocks.com/guides/compliance-exports.md)
>
> Auditdaten in SOC 2-, GDPR- und HIPAA-Formaten exportieren.

> [card] [Missbrauchshärtung](https://docs.truthlocks.com/security/abuse-hardening.md)
>
> Missbrauch mithilfe von Auditdaten erkennen und verhindern.

> [card] [Ratenbegrenzungen](https://docs.truthlocks.com/ops/limits.md)
>
> Verstehen Sie das Verhalten der Ratenbegrenzung in Audit-Logs.


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