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

# Authentifizierung

> API-Authentifizierungsmethoden, Schlüsselverwaltung und Best Practices für die Sicherheit.

Truthlocks unterstützt mehrere Authentifizierungsmethoden, um den API-Zugriff zu sichern. Dieser Leitfaden behandelt API-Schlüssel, JWT-Tokens und Best Practices für die Sicherheit.

## Authentifizierungsmethoden

> [card] API-Schlüssel
>
> Langlebige Anmeldeinformationen für die Server-zu-Server-Kommunikation. Empfohlen für
> Backend-Dienste.

> [card] Bearer Tokens (JWT)
>
> Kurzlebige Tokens für authentifizierte Benutzer. Ideal für Frontend-Anwendungen
> und Benutzerkontext.

## API-Schlüssel

Truthlocks hat zwei Arten von API-Schlüsseln, je nachdem, wie Sie die Plattform nutzen:

| Typ | Präfix | Erstellt aus | Anwendungsfall |
| :- | :- | :- | :- |
| **Mandantenschlüssel** | `tl_live_` / `tl_test_` | [Console](https://console.truthlocks.com) | Server-zu-Server-Integrationen, Unternehmens-Workflows |
| **Verbraucherschlüssel** | `tlk_` | [Verify portal](https://verify.truthlocks.com) | Persönlicher API-Zugriff für Inhaltsschutz und Verifizierung |

### Schlüssel übergeben

Fügen Sie Ihren API-Schlüssel mit einem dieser Header hinzu:

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

Sie können auch den `Authorization` Header mit dem `ApiKey` Schema verwenden:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "Authorization: ApiKey tl_live_your_api_key"
```

Diese Formate authentifizieren API-Schlüssel-aktivierte Endpunkte. Einige Operationen erfordern ein Benutzer-Bearer-Token und Rollenprüfungen; öffentliche Gesundheitsendpunkte benötigen beides nicht. `X-API-Key` ist in den Beispielen in dieser Dokumentation häufiger anzutreffen.

## Mandanten-API-Schlüssel

Mandantenschlüssel sind die primäre Authentifizierungsmethode für Organisationen, die Truthlocks verwenden. Sie sind auf einen Mandanten beschränkt und unterstützen fein abgestufte Berechtigungen.

### Schlüsselstruktur

```text theme={null}
tl_live_abc123def456gh789ijklmnopqrstuv
│  │    │
│  │    └── 32-character random identifier
│  └── Environment: test | live
└── Prefix: tl (Truthlocks)
```

### Bereiche

Mandanten-API-Schlüssel können auf bestimmte Berechtigungen beschränkt werden:

| Umfang | Berechtigungen |
| - | - |
| `attestations:mint` | Neue Attestierungen erstellen |
| `attestations:read` | Attestierungsdetails und Proof-Bundles lesen |
| `attestations:revoke` | Attestierungen widerrufen |
| `issuers:read` | Ausstellerinformationen anzeigen |
| `issuers:write` | Aussteller erstellen und verwalten |
| `users:read` | Benutzer und Rollen anzeigen |
| `users:write` | Benutzer einladen, Rollen verwalten |
| `audit:read` | Audit-Protokolle abfragen |

> [!NOTE]
>
> **Prinzip der geringsten Privilegien:** Gewähren Sie nur die Bereiche, die Ihre Anwendung benötigt.
> tatsächlich benötigt. Ein Schlüssel mit nur `attestations:mint` sollte nicht auch
> `users:write`.

### Erstellen eines Mandantenschlüssels

#### Über Konsole

1. Navigieren Sie zu [console.truthlocks.com/api-keys](https://console.truthlocks.com/api-keys)
2. Klicken Sie auf „API-Schlüssel erstellen“
3. Geben Sie einen aussagekräftigen Namen ein (z. B. „Produktions-Backend“)
4. Wählen Sie die Umgebung (Produktion oder Sandbox) und die erforderlichen Bereiche aus
5. Kopieren Sie den Schlüssel sofort – er wird nicht wieder angezeigt

#### Über API

```bash Request theme={null}
curl -X POST https://api.truthlocks.com/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "scopes": ["attestations:mint", "attestations:read", "issuers:read"]
  }'
```

```json Response theme={null}
{
  "id": "key-uuid",
  "name": "Production Backend",
  "prefix": "tl_live_abc",
  "secret": "tl_live_abc123def456gh789ijklmnopqrstuv",
  "scopes": ["attestations:mint", "attestations:read", "issuers:read"],
  "created_at": "2026-01-13T12:00:00Z"
}
```

> [!WARNING]
>
> **Kritisch:** Das Feld `secret` wird nur einmal zum Zeitpunkt der Erstellung zurückgegeben. Speichern Sie es
> es sofort in einem Secrets Manager.

## Consumer-API-Schlüssel

Verbraucherschlüssel ermöglichen einzelnen Benutzern den programmatischen Zugriff auf die Protect- und Verify-APIs – zum Beispiel, um Bestätigungen aus einer CI-Pipeline zu prägen oder den Inhaltsschutz in Ihre eigenen Tools zu integrieren.

### Wichtige Details

* Jedes Konto unterstützt bis zu **5 aktive Schlüssel**.
* Schlüssel verfallen automatisch nach **90 Tagen**.
* Widerrufene oder abgelaufene Schlüssel können nicht reaktiviert werden – erstellen Sie stattdessen einen neuen.

### Feste Bereiche

Verbraucherschlüssel werden mit einem festen Satz von Scopes ausgegeben, die nicht angepasst werden können:

| Umfang | Berechtigungen |
| :- | :- |
| `consumer:read` | Ihr Verbraucherprofil und Ihre Einstellungen lesen |
| `consumer:write` | Aktualisieren Sie Ihr Verbraucherprofil und Ihre Einstellungen |
| `attestations:mint` | Neue Attestierungen prägen |
| `attestations:read` | Ihre Attestierungen lesen |
| `verify:read` | Attestierungen verifizieren |

### Erstellen eines Verbraucherschlüssels

**1. Einstellungen öffnen**

Gehen Sie in der Verify-Portal-Seitenleiste zu **Einstellungen > API-Schlüssel**.

**2. Einen Schlüssel erstellen**

Klicken Sie auf **API-Schlüssel erstellen**, geben Sie einen aussagekräftigen Namen ein und bestätigen Sie. Der vollständige
Geheimnis wird einmal angezeigt – kopieren und sicher speichern.

**3. Schlüssel verwenden**

Übergeben Sie den Schlüssel im `X-API-Key` Header bei jeder Anfrage:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/consumer/protections \
  -H "X-API-Key: tlk_your_key_here"
```

Ausführliche Informationen zur Verwaltung von Verbraucherschlüsseln finden Sie im [Verbraucherportal-Leitfaden](https://docs.truthlocks.com/de/guides/consumer-portal.md#api-keys).

## Bearer-Tokens (JWT)

JWT-Token werden verwendet, wenn Sie API-Aufrufe im Namen eines authentifizierten Benutzers tätigen müssen, z. B. von einer Web- oder Mobilanwendung aus.

### Verwendung von Bearer-Tokens

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

### Token-Struktur

```json theme={null}
{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "email": "user@example.com",
  "roles": ["admin"],
  "iat": 1705147200,
  "exp": 1705150800,
  "iss": "https://auth.truthlocks.com"
}
```

### Token-Lebensdauer

| Token-Typ | Lebensdauer | Aktualisieren |
| - | - | - |
| Zugriffs-Token | 1 Stunde | Über Refresh-Token |
| Refresh Token | 30 Tage | Per erneuter Authentifizierung |

## Authenticator-MFA für Console-Konten

Öffnen Sie in der Console **Einstellungen → Sicherheit → Authentifikator MFA**, um Google Authenticator oder eine andere zeitbasierte Authentifikator-App zu verbinden.

1. Bestätigen Sie Ihr aktuelles lokales Truthlocks-Passwort.
2. Scannen Sie den privaten QR-Code oder geben Sie den Einrichtungsschlüssel in Ihrem Authentifikator als zeitbasiertes Konto ein.
3. Geben Sie den sechsstelligen Code aus der App ein, um MFA zu aktivieren.
4. Speichern Sie die zehn Wiederherstellungscodes, die nach der Bestätigung angezeigt werden. Sie werden einmal angezeigt, und jeder Code funktioniert einmal.

Neue Anmeldungen erfordern den zweiten Faktor entweder nach Ihrem Passwort oder Ihrem Geschäftsidentitätsanbieter. Der Verifizierungsschritt läuft nach fünf Minuten ab. Wiederholte falsche Codes sperren die Verifizierung für das Konto vorübergehend. Ein bereits akzeptierter Code kann nicht wiederverwendet werden.

Um Wiederherstellungscodes zu ersetzen oder MFA zu deaktivieren, bestätigen Sie Ihr Passwort und einen neuen Authentifizierungscode oder einen unbenutzten Wiederherstellungscode. Das Ersetzen von Wiederherstellungscodes macht den vorherigen Satz ungültig. SSO-Benutzer, die noch nie ein lokales Truthlocks-Passwort festgelegt haben, können den Passwort-Reset-Flow für ihre registrierte E-Mail vor der Registrierung verwenden.

Die MFA-Registrierung gilt für Ihr eigenes Konto. Sie registriert keine anderen Mitglieder und erzwingt keine Workspace-weite MFA-Anforderung. Das Aktivieren von MFA widerruft nicht automatisch bestehende Sitzungen. API-Schlüssel bleiben separate Systemanmeldeinformationen.

## Best Practices für die Sicherheit

> [card] ✅ Geheimnisverwaltung verwenden
>
> Speichern Sie API-Schlüssel in Google Secret Manager, HashiCorp Vault oder Ähnlichem. Niemals
> Schlüssel im Anwendungscode fest codieren.

> [card] ✅ Schlüssel regelmäßig rotieren
>
> Erstellen Sie regelmäßig neue Schlüssel und widerrufen Sie alte. Verwenden Sie aussagekräftige Namen mit
> Daten (z. B. „Backend-2026-Q1“).

> [card] ✅ Scopes einschränken
>
> Gewähren Sie nur die tatsächlich benötigten Berechtigungen. Überprüfen und auditieren Sie die Schlüsselbereiche
> regelmäßig.

> [card] ❌ Niemals im Frontend offenlegen
>
> API-Schlüssel sollten niemals in clientseitigem JavaScript enthalten sein. Verwenden Sie JWT-Token
> für die Frontend-Authentifizierung.

> [card] ❌ Niemals in Git committen
>
> Verwenden Sie Umgebungsvariablen oder Geheimnisverwaltung. Fügen Sie `.env*` hinzu
> `.gitignore`.

## Nächste Schritte

> [card] [Verbraucherportal](https://docs.truthlocks.com/guides/consumer-portal.md)
>
> Verwalten Sie Consumer-API-Schlüssel, Schutzmaßnahmen und Einstellungen.

> [card] [Umgebungen](https://docs.truthlocks.com/environments.md)
>
> Sandbox vs. Produktionskonfiguration und Basis-URLs.

> [card] [RBAC & Berechtigungen](https://docs.truthlocks.com/security/rbac.md)
>
> Verstehen Sie Rollen, Berechtigungen und Zugriffssteuerung.

> [card] [Audit-Protokolle](https://docs.truthlocks.com/security/audit.md)
>
> Verfolgen Sie alle API-Aktivitäten und Sicherheitsereignisse.


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