# Authentifizierung und Idempotenz

Zugangsdaten, Berechtigungsbereiche, Idempotency-Key und Anfrage-IDs für jeden SciFig-API-Aufruf.

Quelle: https://scifig.ai/de/docs/api/authentication

## Bearer-Authentifizierung

Senden Sie `Authorization: Bearer <credential>` bei jeder Anfrage außer `GET /pricing`, `GET /openapi.json` und `GET /openapi.yaml`. Zugangsdaten in Abfrageparametern oder anderen Headern werden ignoriert.

Zugangsdaten verwenden Bearer-Authentifizierung; DPoP-gebundene Zugangsdaten werden nicht unterstützt.

- API-Schlüssel beginnen mit `sk_live_`. Erstellen Sie sie unter Einstellungen → Entwickler; der Schlüssel wird nur einmal angezeigt. Bewahren Sie ihn auf einem Server auf und liefern Sie ihn niemals in einer Browser- oder Mobil-App aus. Sie erhalten 7 Tage vor Ablauf eine E-Mail von uns.
- OAuth-Zugriffstoken beginnen mit `sf_at_`. MCP-Clients erhalten sie nach Ihrer Zustimmung; unter Einstellungen → Entwickler → Verbundene Apps können Sie einen Client trennen.
- Fehlende, ungültige, abgelaufene oder widerrufene Zugangsdaten führen zu `401 UNAUTHORIZED`. Ein Konto, das die API nicht nutzen kann, etwa weil es gelöscht wird, führt zu `401 ACCOUNT_UNAVAILABLE`.
- Der Widerruf eines Schlüssels verhindert neue Anfragen mit diesem Schlüssel. Bereits erstellte Aufträge laufen weiter und können mit anderen Zugangsdaten desselben Kontos abgefragt werden.

## Berechtigungsbereiche

| Berechtigungsbereich | Berechtigungen | API-Schlüsseltyp |
| --- | --- | --- |
| figures:read | `GET /jobs`, `GET /jobs/{id}`, `GET /files/{file_id}`, `GET /credits` | Leseschlüssel; kann unbegrenzt gültig sein |
| figures:generate | Alles aus `figures:read` sowie jeder `POST`-Endpunkt | Generierungsschlüssel; läuft nach 30 Tagen, 90 Tagen oder 1 Jahr ab; erfordert ein aktives Abonnement oder ein positives Guthaben aus Credit-Paketen |

Eine Anfrage außerhalb des Berechtigungsbereichs der Zugangsdaten führt zu `403 SCOPE_DENIED`. Verwenden Sie für jede Anwendung und Umgebung einen eigenen Schlüssel, damit Sie einen widerrufen können, ohne andere zu beeinträchtigen.

## Idempotenz

- Jede Erstellungsanfrage (`POST /images/*`, `/charts/*`, `/flowcharts/*`) erfordert einen `Idempotency-Key`-Header mit 1–255 sichtbaren ASCII-Zeichen. Eine zufällige UUID pro Anfrage ist die einfachste Wahl. Auch Uploads an `POST /files` können einen solchen Header senden; siehe [Dateien](/de/docs/api/files#upload).
- Derselbe Schlüssel mit demselben Anfrageinhalt gibt denselben Auftrag zurück und reserviert keine weiteren Credits. Bei Diagrammuploads gehören die Bytes der Datendatei zum Anfrageinhalt.
- Derselbe Schlüssel mit einem anderen Anfrageinhalt führt zu `409 IDEMPOTENCY_CONFLICT`. Gleichzeitige Anfragen mit demselben Schlüssel erstellen niemals zwei Aufträge: Jede gibt denselben Auftrag zurück oder `409 IDEMPOTENCY_IN_PROGRESS` mit `Retry-After: 1`, während die erste Anfrage noch angenommen wird.
- Wiederholen Sie die Anfrage nach einem Zeitlimit, Netzwerkfehler, `429` oder `503` mit demselben Schlüssel. Nur so lässt sich sicherstellen, dass kein zweiter Auftrag erstellt wird.
- Sobald der Auftrag existiert, enthält ein wiederholbarer Fehler (`429`, `503`, `409 IDEMPOTENCY_IN_PROGRESS`) oder `500 INTERNAL_ERROR` das Feld `details.job_id`. Wiederholen Sie die Anfrage mit demselben Schlüssel oder fragen Sie `GET /jobs/{job_id}` ab. Wechseln Sie nicht zu einem neuen Schlüssel, da dies einen zweiten kostenpflichtigen Auftrag erstellt. Ein angenommener Auftrag, der nicht zurückgelesen werden konnte, wird mit `202` und Status `queued` beantwortet.
- Eine abgelehnte Anfrage, etwa `402 INSUFFICIENT_CREDITS`, behält diese Antwort für ihren Schlüssel. Senden Sie sie nach dem Aufladen oder Tarifwechsel mit einem neuen Schlüssel erneut.

## OAuth-Clients

- MCP-Clients verwenden OAuth 2.1 mit PKCE. Zugriffstoken (`sf_at_…`) gelten 1 Stunde. Ein Client, der den Berechtigungsbereich `offline_access` anfordert, erhält zusätzlich ein 30 Tage gültiges Aktualisierungstoken (`sf_rt_…`) und bleibt verbunden, bis Sie ihn trennen. Ohne `offline_access` müssen Sie sich nach Ablauf des Zugriffstokens erneut anmelden.
- Aktualisierungstoken werden rotiert: Jede Aktualisierung gibt ein neues Token zurück. Ein bereits verwendetes Aktualisierungstoken erneut vorzulegen, gilt als Wiederverwendung und widerruft die daraus ausgestellten Token. Der Client muss sich dann erneut anmelden.
- Die dynamische Clientregistrierung akzeptiert einen Anfrageinhalt von höchstens 16 KB, mit Limits für die Feldlängen und die Anzahl der Weiterleitungs-URIs. Die Authentifizierung am Token-Endpunkt ist `none` für öffentliche Clients mit PKCE oder `client_secret_basic`.
- Ein registrierter, aber nie autorisierter Client wird nach 24 Stunden gelöscht.
- Eine Autorisierungsanfrage mit `prompt=login` oder `max_age` verlangt eine erneute Anmeldung. Wenn Sie bereits angemeldet sind, bittet SciFig um Ihre Bestätigung, bevor es Sie ab- und wieder anmeldet.
- Limits für OAuth-Zugangsdaten gelten pro Client und Konto. Andere Nutzer desselben Assistenten verbrauchen dadurch nicht Ihre Limits.

## Anfrage-IDs

Jede Antwort enthält `X-Request-Id`; Fehlerantworten wiederholen den Wert als `error.request_id`. Die ID kennzeichnet die Anfrage in unseren Protokollen, ohne weitere Informationen offenzulegen. Sie können sie daher bedenkenlos protokollieren und bei einer Supportanfrage angeben.