API-Schlüssel

Der Zugriff auf APIs kann mit API-Schlüsseln effizient verwaltet werden.

Ossi Galkin avatarGeschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contents

API-Schlüssel werden verwendet, um einen Anrufer zu authentifizieren, der einen HTTP- oder API-Trigger mithilfe der API-Schlüsselauthentifizierung auslöst. Jeder API-Schlüssel ist nur für eine bestimmte Umgebung gültig und die Zugriffsrechte für einen API-Schlüssel werden durch die darauf angewendeten Regelsätze bestimmt.

Regelsätze

Regelsätze werden verwendet, um Zugriffsregeln für API-Schlüssel zu gruppieren, und sie werden von allen Umgebungen gemeinsam genutzt. Dadurch kann ein Partner oder ein System identische Zugriffsrechte für mehrere Umgebungen haben, indem API-Schlüssel für alle Umgebungen mit denselben Regelsätzen gemeinsam genutzt werden. Ein API-Schlüssel kann mehrere aktive Regelsätze gleichzeitig haben.

Im obigen Beispiel hat System X Zugriff auf die Entwicklungs-, Test- und Produktionsumgebung (mit unterschiedlichen Schlüsseln). Es gelten jedoch genau dieselben Zugriffsregeln, da alle denselben Regelsatz verwenden. Das bedeutet, wenn in der Testumgebung alles wie erwartet funktioniert, können wir sicher sein, dass ein Schlüssel mit denselben Regelsätzen auch in der Produktion funktioniert.

Regeln

Ein Regelsatz besteht aus einfachen Regeln, die dem Benutzer Zugriff auf einen bestimmten URL-Pfad gewähren, wenn dieser mit einer bestimmten Methode aufgerufen wird. Pfadparameter sindnichtim Regelsatz unterstützt.

Der Agent, der den HTTP(S)-Aufruf an einen HTTP- oder API-Trigger empfängt, setzt die Regeln durch. Der Agent kennt alle API-Schlüssel für die Umgebung, in der er arbeitet, und die angewendeten Regelsätze. Für jede Regel, die auf einen API-Schlüssel zutrifft, prüft der Agent den Pfad des Aufrufs und die verwendete Methode. Wenn der Pfad mit demselben Pfad wie die Regel beginnt und die Methode übereinstimmt, wird der Aufruf durchgelassen.

Beispiel
Angenommen, ein Agent arbeitet anhttps://agent.org:9999und es erfolgt ein Anruf anhttps://agent.org.9999/api/myApi/v2/getStatus?paging=4

Der Teil des Anrufs, der den Zugriff bestimmt, ist/api/myApi/v2/getStatus, und der Rest wird ignoriert.

Nehmen wir an, dieser Aufruf erfolgt mit der GET-Methode.

Wenn eine Regel mit dem Pfad gesetzt ist/API/und die MethodeBELIEBIG, kann der Aufruf durchgehen, da der Pfad mit derselben Zeichenfolge beginnt und jede Methode zulässig ist. Wenn jedoch eine Regel so konfiguriert ist, dass sie/api/myApi/v1, wird der Anruf nicht durchgestellt, da der Anfang der Pfade nicht vollständig übereinstimmt.

Beachten Sie, dass beim Vergleich zwischen Regelpfad und Aufrufpfad die Groß-/Kleinschreibung nicht beachtet wird.

Konfiguration

API-Schlüssel und Regelsätze werden auf der Seite „Verwaltung“ -> „API-Schlüssel“ verwaltet.

Regelsätze

Regelsätze bestehen aus einer Sammlung von Regeln, jede mit einem Pfad und einer Methode. Durch Klicken auf den Pfad können Sie die von der Regel abgedeckten API-Spezifikationen anzeigen. Wenn ein vollständiger Basispfad einer API-Spezifikation abgedeckt ist, zeigt die Liste die in der Spezifikation abgedeckten Vorgänge an.

Beachten Sie, dass die Liste keine Vorgänge enthält, die Pfadparameter enthalten, da diese möglicherweise von der Regel abgedeckt sind, dies jedoch nicht muss.

Ein Regelsatz enthält eine Liste der API-Schlüssel, die ihn verwenden. Neue Schlüssel können einfach hinzugefügt oder alte Schlüssel entfernt werden. Immer wenn ein Regelsatz geändert wird, werden Aktualisierungen an die Agenten gesendet.

API-Schlüssel

API-Schlüssel werden für jede Umgebung erstellt und können nicht auf andere übertragen oder dupliziert werden. Sobald bei der Erstellung eines Schlüssels eine Umgebung angegeben wurde, kann sie anschließend nicht mehr geändert werden. Nach dem Speichern des Schlüssels wird ein Wert für seine Verwendung generiert. Auf der API-Schlüsselseite können Regelsätze hinzugefügt oder entfernt werden, die sich auf den API-Schlüssel auswirken sollen.

Drosselung

Agenten und API-Gateways können einfache Drosselungen für Anfragen basierend auf API-Schlüsseln durchführen. Wenn das „Anforderungslimit“ für einen API-Schlüssel konfiguriert ist, überprüft der Agent (oder das API-Gateway), dass der Schlüssel innerhalb des definierten Zeitraums nicht öfter als die angegebene Anzahl verwendet wird. Ein neuer Zeitraum beginnt mit der ersten Anfrage mit einem bestimmten API-Schlüssel. Wenn während des Zeitraums mehr Anfragen eingehen als das angegebene Limit, erhalten die zusätzlichen Aufrufe eine HTTP 429-Antwort.

Bitte beachten Sie, dass die Grenzwerte derzeit pro Instanz des Agenten (oder API-Gateways) überprüft werden. Dies bedeutet, dass in einer Umgebung mit Lastenausgleich die effektiven Grenzwerte entsprechend der Anzahl der Agenten skaliert werden. Wenn beispielsweise der Grenzwert für API-Schlüsselanforderungen auf 100 pro Stunde festgelegt ist und sich in einer Agentengruppe zwei Agenten befinden, beträgt der effektive Grenzwert etwa 200 Anforderungen pro Sekunde. Der effektive Grenzwert könnte auch etwas niedriger sein, je nachdem, wie gleichmäßig der Lastenausgleich die Last verteilt. Sobald einer der Agenten den Anforderungsgrenzwert erreicht, beginnt er, HTTP 429-Antworten zurückzugeben, auch wenn der andere Agent seinen Grenzwert noch nicht erreicht hat.

Verwenden von API-Schlüsseln von der Seite „Agent API Discovery“

Sobald die API-Schlüssel und das Regelwerk eingerichtet wurden und ein Prozess vorhanden ist, der die API-Schlüsselauthentifizierung verwendet, können Sie auf der Seite „Agent API Discovery“ einen API-Schlüssel eingeben. Der API-Schlüssel wird der Anfrage als Header hinzugefügt (X-ApiKey).

Übergeben eines API-Schlüssels von einem Client

Ein API-Schlüssel kann entweder in den in der API-Spezifikation angegebenen Anforderungsheadern oder in Abfrageparametern übergeben werden.


In Version 5.3.3 und früher musste der API-Schlüssel entweder innerhalb des Authorization-Headers mit demAPI-SchlüsselTyp oder mit demX-API-SchlüsselKopfzeile.

Zum Beispiel:Autorisierung: ApiKey 12345678-1234-1234-1234-1234567890aboder:X-ApiKey: 12345678-1234-1234-1234-1234567890ab


Verwandte ArtikelAuthentifizierung zum Anzeigen der API-SpezifikationenEinführung in die Konfiguration einer Authentifizierungsmethode für eine APIEinführung in API-SchlüsselBeispiel zum Erstellen von API-SchlüsselnEinführung in die Weitergabe eines API-Schlüssels an die Frends API von einem Client