SYNDERESIS / API START
Gehostete Kunden-API · Vertrag überprüft am 7. November 2026
Authentifizierung und API-Schlüssel
Auf dieser Seite
Verwenden Sie einen Kunden-API-Schlüssel von Ihrem Backend aus. Dasselbe Konto besitzt seine Schlüssel, seine Zuteilung, seine Berechtigung und seine Nutzung.
Genau einen Anmeldedaten-Header senden
Bevorzugt:
Authorization: Bearer <key>
Content-Type: application/json
Alternative:
X-API-Key: <key>
Content-Type: application/json
Die Beispiele zeigen die Header-Syntax; ersetzen Sie den Schlüssel über einen Secret-Manager oder eine Umgebungsvariable. Senden Sie niemals beide Schlüssel-Header. Der Authorization-Wert muss genau das gezeigte Bearer-Schema verwenden. Legen Sie einen Schlüssel nicht in einen Query-String, ein öffentliches Repository, Browser-JavaScript, ein mobiles Bundle oder eine herunterladbare Konfiguration.
Header-Namen sind unabhängig von der Groß- und Kleinschreibung. Werte der Anmeldedaten sind Geheimnisse und müssen exakt unverändert bleiben. Kopierfehler am Anfang oder am Ende oder ein abgeschnittener Schlüssel können einen 401 verursachen.
Schlüssel erstellen und speichern
Melden Sie sich im Konto an und erstellen Sie einen Kunden-API-Schlüssel. Speichern Sie den vollständigen Schlüssel, wenn er angezeigt wird; spätere Schlüsselauflistungen enthalten sein Präfix und Metadaten, nicht den vollständigen Wert.
Das Konto kann bis zu 10 aktive Kunden-/Erweiterungsschlüssel halten. Serverseitig verwaltete Browser-Metering-Schlüssel belegen keinen Kundenplatz und erscheinen nicht in der Liste der Kundenschlüssel. Ein neuer Schlüssel teilt sich die bestehende Kontobefugnis und das bestehende Kontingent.
Die Registrierung stellt nicht automatisch einen Kundenschlüssel aus. Eine Website-Sitzung und ein API-Schlüssel sind unterschiedliche Anmeldedaten.
Gemeinsame Schlüssel nur für Inferenz
Ein gemeinsamer Schlüssel nur für Inferenz beginnt mit sk_inf_. Er wird von einem Betreiber an eine eigene dedizierte Identität ausgegeben; er wird nicht im Konto erstellt und ist nicht einer der Kundenschlüssel Ihres Kontos. Er kann nur POST /v1/chat/completions, POST /v1/answers und GET /v1/models aufrufen; jede andere Route antwortet mit HTTP 403 inference_scope_denied. Seine gespeicherte Token-Obergrenze für die Lebensdauer und sein Ablauf werden unter Grenzwerte und Abrechnung beschrieben. Eine Anfrage bei oder nach seinem Ablauf wird mit HTTP 401 unauthorized abgelehnt.
Getrennte Umgebungen
Erstellen Sie getrennte Schlüssel für Entwicklung, Staging und Produktion, soweit das Schlüssellimit des Kontos dies zulässt. Speichern Sie jeden Schlüssel nur in der Bereitstellung, die ihn benötigt. Überwachen Sie anhand des Schlüsselpräfixes und halten Sie den vollständigen Wert aus Logs, Traces, Absturzberichten und Supportanfragen heraus.
Getrennte Schlüssel teilen sich weiterhin die Limits des Kontos. Verwenden Sie getrennt bereitgestellte Konten oder eine gesondert vereinbarte Dienstvereinbarung, wenn Sie eine stärkere organisatorische Isolation oder unabhängig verwaltete Quoten benötigen.
Schlüssel rotieren
- Erstellen Sie einen Ersatzschlüssel im Konto.
- Speichern Sie ihn im zugehörigen Secret-Manager.
- Aktualisieren Sie den Dienst und prüfen Sie eine authentifizierte Anfrage.
- Widerrufen Sie den vorherigen Schlüssel im Konto.
- Bestätigen Sie, dass die übrigen Dienste gewechselt haben.
Die Rotation ist dieser Ablauf aus Ersetzen und Widerrufen; die geprüfte Kunden-API stellt keinen dedizierten Rotationsendpunkt und kein dokumentiertes Versprechen einer Übergangsfrist bereit.
Wenn ein Schlüssel möglicherweise durchgesickert ist, widerrufen Sie ihn und ersetzen Sie ihn. Prüfen Sie unerwartete Nutzung und entfernen Sie den offengelegten Wert aus der betroffenen Konfiguration. Senden Sie den alten oder den neuen Schlüssel nicht an den Support.
Grenze der Schlüsselverwaltungs-API
Die Website verwendet GET/POST /v1/account/keys und DELETE /v1/account/keys/{prefix}, um Schlüssel zu verwalten. Dies sind sitzungsautorisierte Kontosteuerungen. Ein Kunden-API-Schlüssel reicht nicht aus, um andere Schlüssel zu verwalten oder auszustellen.
Zustandsverändernde Anfragen der Browser-Sitzung erfordern außerdem die CSRF-Schutzmaßnahmen des Dienstes. Verwenden Sie Konto für den normalen Ablauf der Schlüsselverwaltung; verpflanzen Sie keine Browser-Cookies in ein Server-SDK.
Authentifizierungsfehler
| Symptom | Aktion |
|---|---|
| Fehlender API-Schlüssel | Prüfen Sie die Umgebung im tatsächlichen Serverprozess und senden Sie einen Header mit Anmeldedaten. |
| Ungültiger API-Schlüssel | Prüfen Sie das Kopieren, Widerruf/Ablauf und das Konto; erstellen Sie bei Bedarf einen Ersatz. |
| Beide Header übermittelt | Entfernen Sie einen davon. Verlassen Sie sich nicht auf den Vorrang der Header. |
| Authorization-Schema abgelehnt | Verwenden Sie Authorization: Bearer, gefolgt vom Schlüssel, oder verwenden Sie X-API-Key. |
| Cookie funktioniert auf einer Website, aber das SDK schlägt fehl | Geben Sie einen Kunden-API-Schlüssel an; der Transkript-/Tool-Chatpfad akzeptiert keine Sitzung allein. |
| Origin- oder CSRF-Fehler | Halten Sie Serveraufrufe frei von Sitzungscookies des Browsers; verwenden Sie für Steuerungen im Browser die unterstützte Benutzeroberfläche des Kontos. |
| 403 inference_scope_denied | Ein gemeinsam genutzter, ausschließlich für die Inferenz vorgesehener Schlüssel hat eine Route außerhalb seines Geltungsbereichs aufgerufen. Verwenden Sie ihn nur für Antworten, Chat-Vervollständigungen und die Modellermittlung. |
Eine Anfrage kann schon vor der Authentifizierung an der Validierung von Modell oder Body scheitern. Eine unsupported_model-Antwort belegt nicht, dass ein übermittelter Schlüssel gültig ist.
Siehe Hinweise für den Produktivbetrieb zu Anfrage-IDs, Wiederholungsversuchen und betrieblicher Protokollierung.