# Authentifizierung Jede API-Anfrage muss Ihren API-Schlüssel enthalten, damit Your AI Connector weiß, wer Sie sind und für welches Konto die Aktion ausgeführt werden soll. Sie können den Schlüssel auf vier verschiedene Arten senden – alle funktionieren bei jedem Endpunkt, der eine API-Schlüssel-Authentifizierung akzeptiert. Wählen Sie also die Methode, die am besten zu Ihrem Setup passt. Der API-Zugriff ist eine kostenpflichtige Funktion. Wenn Ihr Plan diese nicht beinhaltet, werden Anfragen mit einem `403` abgelehnt, selbst wenn der Schlüssel an sich gültig ist – siehe [Die Schranke für kostenpflichtige Funktionen](#the-paid-feature-gate) weiter unten. Informationen zum Generieren eines Schlüssels finden Sie unter [API-Zugriff](../integrations/api-access.md). > **Nur HTTPS.** Alle Anfragen müssen über eine sichere Verbindung erfolgen. Unverschlüsselte HTTP-Anfragen werden abgelehnt, noch bevor die Authentifizierung überhaupt ausgeführt wird. --- ## Die vier Methoden im Überblick | Methode | Übertragung | Wann zu verwenden | |---|---|---| | Abfrageparameter | `?apiKey=YOUR_API_KEY` | Schnelle Tests und Browser-URLs | | Header | `X-API-Key: YOUR_API_KEY` | Produktionsintegrationen | | Bearer-Header | `Authorization: Bearer YOUR_API_KEY` | Produktionsintegrationen | | Firebase-ID-Token | `Authorization: Bearer ` | Nur für First-Party-App-Sitzungen | Wenn mehr als eine Methode vorhanden ist, hat der Abfrageparameter Vorrang, gefolgt vom `X-API-Key`-Header und dann dem Bearer-Token. In der Praxis senden Sie ohnehin immer nur eine Methode. --- ## 1. Abfrageparameter — `?apiKey=` Fügen Sie Ihren Schlüssel an das Ende der Webadresse an. Dies ist die einfachste Form und funktioniert immer, was sie ideal für schnelle Tests, Skripte und ältere Tools macht. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", params={"apiKey": "YOUR_API_KEY"}, ) data = res.json() ``` > **Hinweis:** Webadressen landen im Browserverlauf, in Server-Zugriffsprotokollen und Proxy-Logs. Verwenden Sie für alles, was über einen schnellen Test hinausgeht, bevorzugt eine der unten genannten Header-Methoden, damit Ihr Schlüssel nicht im Klartext auf die Festplatte geschrieben wird. --- ## 2. `X-API-Key`-Header Senden Sie den Schlüssel in einem dedizierten Header. Dies hält ihn aus der URL fern und ist die empfohlene Wahl für die Produktion. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` --- ## 3. `Authorization: Bearer` Header Sie können den Schlüssel auch als Standard-Bearer-Token übergeben. Dies ist praktisch, wenn Ihr HTTP-Client oder Framework bereits integrierte Unterstützung für `Authorization`-Header bietet. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts", { headers: { Authorization: "Bearer YOUR_API_KEY", }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) data = res.json() ``` Die API unterscheidet automatisch zwischen Ihrem API-Schlüssel und einem Login-Token, daher funktioniert diese Methode genau wie `X-API-Key`. --- ## 4. Firebase ID-Token (nur für First-Party) Wenn Sie eine First-Party-App entwickeln, bei der sich Benutzer über das eigene Login von Your AI Connector anmelden, können Sie das Firebase ID-Token des angemeldeten Benutzers anstelle eines API-Schlüssels als Bearer-Token übergeben: ``` Authorization: Bearer ``` Das Token wird bei jeder Anfrage überprüft und dem angemeldeten Konto zugeordnet. **Diese Methode ist nur für First-Party-App-Sitzungen vorgesehen** – Sie können diese Token nicht über eine externe Integration erstellen, und es gibt keine Möglichkeit, eines ohne den normalen App-Login zu erhalten. Verwenden Sie für Server-zu-Server- und Drittanbieter-Integrationen einen API-Schlüssel (Methoden 1–3). --- ## Wann welche Methode zu verwenden ist - **Schnelle Tests und einmalige Skripte** → Abfrageparameter (`?apiKey=`). Am schnellsten einzugeben, funktioniert im Browser. - **Produktionsintegrationen und Server-zu-Server-Aufrufe** → `X-API-Key` oder `Authorization: Bearer YOUR_API_KEY`. Hält den Schlüssel aus URLs und Protokollen fern. - **First-Party-Apps mit einem angemeldeten Your AI Connector-Benutzer** → `Authorization: Bearer `. --- ## Schlüsselbereiche Ihr Konto verfügt über einen **Haupt-API-Schlüssel** – diesen finden Sie unter **Einstellungen → Integrationen → API-Schlüssel**. Er bietet vollen Zugriff auf alle Funktionen des Kontos. Sie können auch zusätzliche **bereichsbezogene Schlüssel** erstellen: benannte Schlüssel, die nur auf die von Ihnen gewählten Teile der API zugreifen können, zum Beispiel ein schreibgeschützter Schlüssel, der für ein Reporting-Dashboard auf Analysedaten beschränkt ist. Ein bereichsbezogener Schlüssel wird genau wie der Hauptschlüssel verwendet (über eine der Methoden 1–3 oben), wird jedoch bei jeder Anfrage anhand seiner eigenen Berechtigungen geprüft: - **Außerhalb der erlaubten Bereiche wird der Zugriff verweigert.** Ein Schreibzugriff mit einem schreibgeschützten Schlüssel oder ein Aufruf eines Bereichs, für den der Schlüssel nicht autorisiert ist, führt zu `403` – `key_read_only` oder `key_scope_denied` im Feld `error_code`. Die Prüfung ist bewusst streng: Alles, was nicht eindeutig innerhalb der erlaubten Bereiche des Schlüssels liegt, wird abgelehnt, anstatt es zuzulassen. Wenn Sie also einen dieser `403`-Fehler sehen, deckt der Schlüssel diesen Endpunkt schlichtweg nicht ab. - **Er verfügt über ein eigenes Ratenlimit-Budget.** Ein bereichsbezogener Schlüssel wird separat von Ihrem Hauptschlüssel gezählt, sodass ein ausgelastetes Dashboard, das einen bereichsbezogenen Schlüssel verwendet, nicht das Kontingent aufbrauchen kann, von dem Ihre anderen Integrationen abhängen. Sie legen dieses Budget pro Minute bei der Erstellung des Schlüssels fest. - **Er kann keine API-Schlüssel verwalten.** Nur der Kontoinhaber – angemeldet oder unter Verwendung des Hauptschlüssels – kann Schlüssel auflisten, erstellen, bearbeiten, rotieren oder widerrufen. Ein bereichsbezogener Schlüssel kann niemals einen umfassenderen Schlüssel für sich selbst erstellen. Unter [API-Schlüssel](api-keys.md) erfahren Sie, wie Sie bereichsbezogene Schlüssel erstellen, bearbeiten und widerrufen. --- ## Die Bezahlschranke für Funktionen Der API-Zugriff ist eine kostenpflichtige Funktion. Wenn Ihr Tarif diese nicht beinhaltet, wird eine Anfrage mit einem ansonsten gültigen Schlüssel mit `403` abgelehnt: ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` If you see this, check your plan or contact [hi@youraiconnector.com](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead: ```json { "success": false, "error_code": 401, "error": "Invalid API key" } ``` --- ## Sicherheit Ihres Schlüssels - **Behandeln Sie den Schlüssel wie ein Passwort.** Ihr Hauptschlüssel gewährt vollen Zugriff auf Ihr Konto. Wenn Sie ein Tool oder eine Person mit einem Schlüssel ausstatten müssen, die nur eingeschränkten Zugriff benötigt, erstellen Sie stattdessen einen bereichsbezogenen Schlüssel – siehe [Schlüsselbereiche](#key-scopes). - **Bewahren Sie ihn serverseitig auf.** Betten Sie ihn niemals in Browser-JavaScript, ein mobiles App-Paket oder einen anderen Code ein, den ein Endbenutzer lesen kann. - **Speichern Sie ihn in einem Secret-Manager** oder einer serverseitigen Konfiguration, nicht in der Quellcodeverwaltung. - **Rotieren Sie ihn bei einem Leck.** Generieren Sie einen neuen Schlüssel über das Dashboard oder rufen Sie `POST https://api.youraiconnector.com/v1/api-keys/rotate` auf – dies macht den alten sofort ungültig. Siehe [API-Schlüssel](api-keys.md). - **Verwenden Sie immer HTTPS**, damit der Schlüssel bei der Übertragung verschlüsselt ist. --- ## Nächste Schritte - [Erste Schritte](getting-started.md) – Ihre erste Anfrage und die Ressourcen-Leitfäden. - [Fehler & Paginierung](errors-and-pagination.md) – Umgang mit Fehlern und das Blättern durch Ergebnisse. - [API-Schlüssel](api-keys.md) – Rotieren, Widerrufen und Überprüfen der Nutzung Ihres Schlüssels.