# Authentifizierung und Schlüssel

> Authentifizierung mit Bearer-API-Schlüsseln. Live- und Testschlüssel, was der Testmodus liefert, Schlüssel widerrufen und ein monatliches Ausgabenlimit pro Schlüssel festlegen.

Quelle: https://fileverity.com/de/docs/authentication

Jede Anfrage braucht einen API-Schlüssel, der als Bearer-Token im Header `Authorization` gesendet wird.

**Authentifizierte Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/models \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Authentifizierte Anfrage: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/models", {
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
});
```

**Authentifizierte Anfrage: Python**

```python
import os
import requests

requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})
```

Schlüssel sind vertraulich. Rufen Sie die API von Ihrem Server aus auf, speichern Sie Schlüssel in Umgebungsvariablen oder einem Secrets-Manager und legen Sie sie nie in Browser-Code oder mobilen Apps ab.

## Live- und Testschlüssel

Ein Schlüssel besteht aus `fv_live_` oder `fv_test_`, gefolgt von 40 Buchstaben und Ziffern. Das Präfix legt den Modus fest.

|  | Live-Schlüssel | Testschlüssel |
| --- | --- | --- |
| Präfix | `fv_live_...` | `fv_test_...` |
| Führt die Modelle aus | Ja | Nein |
| Wird Ihrem Guthaben oder kostenlosen Start belastet | Ja | Nie |
| Ergebnisse | Echt | Feste Beispielergebnisse |
| `livemode` in Antworten | `true` | `false` |
| Webhooks | Gesendet | Nicht gesendet |

Beide Modi nutzen denselben Workspace. Sie verwenden dieselben Endpunkte, dieselbe Validierung, dieselben Rate-Limits und dieselben Fehlercodes, sodass Sie mit einem Testschlüssel entwickeln und zum Livegang nur den Schlüssel austauschen können.

## Verhalten im Testmodus

- **Textprüfungen.** Die Anfrage wird wie eine Live-Anfrage validiert: Mindestlänge, Höchstlänge und Sprachprüfung gelten weiterhin. Die Antwort ist ein festes Ergebnis `human` mit `score` und `ai_fraction` von `0` und ohne `segments`. `usage` wird aus Ihrem Text ermittelt. Es wird nichts berechnet und nichts aufgezeichnet.
- **Dateien.** Uploads werden validiert, die Bytes aber nicht gespeichert, und eine JSON-Upload-Anfrage liefert statt einer echten vorsignierten URL ein Test-Upload-Objekt (`upload.test` ist `true`), bei dem die Datei bereits `uploaded` ist. Dateien sind nach Modus getrennt: Ein Testschlüssel kann keine Live-Dateien lesen, und ein Live-Schlüssel keine Testdateien.
- **Analyse erstellen.** Liefert sofort `200` mit `status: succeeded`, einem festen Beispiel mit der Stufe `L2` und der Aktion `accept` sowie `livemode: false`. Die Analyse-ID beginnt mit `an_test` und ist für dieselbe Datei immer gleich. Die Berichts-ID beginnt mit `FV-TEST-` und hat keine öffentliche Verifizierungsseite. Der Beispielbericht enthält nur die Felder, die im Beispiel vorkommen.
- **Analyse abrufen.** Funktioniert nur mit Analyse-IDs aus den Beispielen. **Analysen auflisten** liefert immer eine leere Liste, **Abbrechen** liefert `not_cancelable`, und es gibt kein Beispiel-PDF. Testschlüssel können weder Live-Analysen noch Live-Berichts-PDFs lesen.

**Beispiel-Textprüfung, Testschlüssel**

```json
{
  "id": "tdet_Qm4vB7nP1sK8tL3wR6yZ2cXa",
  "object": "text.detection",
  "created": 1793664000,
  "model": "fvdoc-3-text-2026-11-03",
  "livemode": false,
  "language": "en",
  "verdict": "human",
  "score": 0,
  "ai_fraction": 0,
  "segments": [],
  "usage": {
    "characters": 1412,
    "free_characters": 0,
    "billed_units": 2
  }
}
```

## Schlüssel erstellen und widerrufen

Verwalten Sie Schlüssel in der Konsole unter **API-Schlüssel**.

- **Erstellen.** Vergeben Sie einen Namen und wählen Sie den Modus. Der vollständige Schlüssel wird nur einmal angezeigt. Fileverity speichert nur einen SHA-256-Hash und die letzten vier Zeichen, ein verlorener Schlüssel lässt sich daher nicht wiederherstellen; erstellen Sie einen neuen.
- **Limit.** Ein Workspace kann bis zu 20 aktive Schlüssel enthalten. Darüber hinaus schlägt das Erstellen eines Schlüssels mit `key_limit` fehl.
- **Zuletzt genutzt.** Die Konsole zeigt, wann jeder Schlüssel zuletzt eine Anfrage gestellt hat.
- **Widerrufen.** Anfragen mit einem widerrufenen Schlüssel schlagen sofort mit `invalid_api_key` fehl.
- **Mitglieder, die den Workspace verlassen.** Verlässt ein Mitglied den Workspace oder wird es entfernt, werden die von ihm erstellten Schlüssel widerrufen. Erstellen Sie Produktionsschlüssel mit einem Konto, das im Workspace bleibt.

### Wenn ein Schlüssel bekannt wird

1. Erstellen Sie einen neuen Schlüssel.
2. Stellen Sie Ihre Software auf den neuen Schlüssel um.
3. Widerrufen Sie den alten Schlüssel.

## Monatliche Ausgabenlimits

Jeder Schlüssel kann ein eigenes monatliches Ausgabenlimit in vollen US-Dollar haben. Nur Inhaber und Admins des Workspace können es festlegen oder ändern, beim Erstellen des Schlüssels oder später mit **Limit ändern**. Ein Schlüssel ohne Limit wird nur durch Ihr Guthaben begrenzt.

- Das Limit zählt, was der Schlüssel im aktuellen Kalendermonat (UTC) ausgegeben hat, und wird am 1. zurückgesetzt.
- Eine Anfrage, mit der der Schlüssel sein Limit überschreiten würde, wird mit `spend_limit_reached` (HTTP 402) abgelehnt, bevor die Arbeit beginnt, und nicht berechnet.
- Prüfungen aus dem kostenlosen Start kosten nichts und zählen nicht. Fehlgeschlagene und abgebrochene Prüfungen werden nicht berechnet und zählen nicht.
- Limits gelten für Live-Schlüssel. Testschlüssel verursachen nie Ausgaben.

> **Hinweis.** Verwenden Sie für jeden Dienst und jede Umgebung einen eigenen Schlüssel mit eigenem Limit. Ein außer Kontrolle geratener Job kann dann nicht mehr ausgeben als das Limit dieses Schlüssels.

## Authentifizierungsfehler

| Code | Status | Bedeutung |
| --- | --- | --- |
| `missing_api_key` | 401 | Es wurde kein Header `Authorization: Bearer` gesendet. |
| `invalid_api_key` | 401 | Der Schlüssel hat ein ungültiges Format, ist unbekannt oder wurde widerrufen. |
| `spend_limit_reached` | 402 | Der Schlüssel hat sein monatliches Ausgabenlimit erreicht. |

Die vollständige Liste finden Sie unter [Fehler](https://fileverity.com/de/docs/errors.md).