Authentifizierung und Idempotenz

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.

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.

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

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

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.